Payment Links API - Testing and Validation

Overview

This document provides guidelines for the Payment Links API to ensure proper integration.

🔧 Getting Started

Prerequisites

Valid Astrapay account
API credentials (client ID and secret)

Authentication

All API requests require OAuth 2.0 authentication using a Bearer token obtained here.

Base URLs

Sandbox: https://api-sandbox.astrapay.com.br/payment-link/v1
Production: https://api.astrapay.com.br/payment-link/v1

Common Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by the client)

📡 API Endpoints

1. Create Payment Link

POST

Creates a new payment link with customizable payment methods and installment options.

Request Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Request Body

{
  "payerName": "João Silva",
  "registrationNumber": "12345678901",
  "amount": 100.00,
  "numbersInstallments": 3,
  "description": "Payment for order #12345",
  "userReference": "order-12345",
  "expirationDays": 7
}

Important Notes:

payerName: Name of the transaction payer
registrationNumber: Payer document identification (CPF/CNPJ)
amount: Transaction amount (minimum 0.01)
numbersInstallments: Number of installments (1-10)
description: Optional transaction description
userReference: Optional client reference for tracking
expirationDays: Link validity period (1-10 days)

Response

{
  "linkPaymentUuid": "c1fac1de-b4f8-4dfe-bdbd-bd0ce9b4c919",
  "payerName": "João Silva",
  "registrationNumber": "12345678901",
  "amount": 100.00,
  "numbersInstallments": 3,
  "status": {
    "code": 1,
    "description": "CREATED"
  },
  "urlPayment": "https://checkout-hml.astrapay.com.br/c1fac1de-b4f8-4dfe-bdbd-bd0ce9b4c919?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "description": "Payment for order #12345",
  "verificationToken": 457856,
  "installmentsOptions": [
    {
      "numberInstallments": 1,
      "amountInstallment": 100.00
    },
    {
      "numberInstallments": 2,
      "amountInstallment": 50.00
    },
    {
      "numberInstallments": 3,
      "amountInstallment": 33.33
    }
  ],
  "userReference": "order-12345",
  "creationDate": "2024-01-15T10:30:00.000Z",
  "expirationDays": 7
}

Important: The linkPaymentUuid is the unique identifier for the payment link, generated by our system and returned in the creation response. This identifier is used for all subsequent operations (consultation, status updates).

2. List Payment Links

GET ``

Retrieves a paginated list of payment links with filtering options.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Query Parameters

startDate (required): Search start date
endDate (required): Search end date
paymentReceipt (optional): Filter by payment receipt
status (optional): Filter by link status
paymentMethod (optional): Filter by payment method
registrationNumber (optional): Filter by registration number
userReference (optional): Filter by user reference
page (optional): Page number (default: 0)
size (optional): Page size (default: 20)
sort (optional): Sorting criteria

Available Status Values

Status	Description
`CREATED`	Payment link has been created and is active
`PAID`	Payment has been successfully processed
`EXPIRED`	Payment link has expired and is no longer valid

Available Payment Methods

Code	Description
`1`	Credit Card
`2`	PIX

Example Request

GET /v1/link-payment?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z&status=CREATED&page=0&size=20

3. Get Payment Link Details

GET /{linkPaymentUuid}

Retrieves detailed information about a specific payment link.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Path Parameters

linkPaymentUuid: The payment link UUID to consult (this is the unique identifier returned when creating the payment link)

4. Generate Payment Link Report

GET /report

Generates a detailed report of payment links with filtering options.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Query Parameters

startDate (required): Report start date
endDate (required): Report end date
paymentReceipt (optional): Filter by payment receipt
status (optional): Filter by link status
paymentMethod (optional): Filter by payment method
registrationNumber (optional): Filter by registration number
userReference (optional): Filter by user reference

🧪

Payment Link Testing

Our payment link supports credit card and PIX payments. Below are the main details for using this functionality:

Credit Card Installments
When creating a payment link, the numbersInstallments field defines the maximum number of installments available for payment. This feature is exclusive to credit card payments.
Link Consultation and Listing
You can consult and list payment links directly through our portal or through integration with our listing and consultation APIs.
Automatic Payments in Test Environment (PIX)
To perform tests with PIX payment, simply create a payment link with an amount ending in 01 cent (examples: 0.01, 1.01, 2.01).
In this configuration, the payment will be processed automatically in 30 seconds, allowing you to easily validate payment flows.