Pular para o conteúdo

Create payment

Creates a payment request for the white-label initiation portal. The response returns an id (payment request identifier) and a redirectUrl where you must send the payer’s browser to continue consent and settlement.

Use redirectUri for the URL on your site that receives the user after the portal completes the journey. It must belong to an allow-listed domain for your sub-tenant.

POST/api/v1/payments

Create payment

Creates a payment request and returns redirectUrl and the new payment request id for the hosted portal journey.

Auth: Bearer Token

Request body

11 campos
redirectUri●
bodystring

HTTPS URL on your domain where the portal redirects after completion. Must be allow-listed for the sub-tenant.

value●
bodynumber

Payment amount in BRL.

details
bodystring

Free-text payment description shown where applicable.

externalId
bodystring

Your own correlation id for the payment request (also usable with Get payment by external ID).

cpfCnpj●
bodystring

CPF of the person who will authorise the payment, digits only. For company payments, send the representative's CPF and the company CNPJ in businessCnpj.

businessCnpj
bodystring

Company CNPJ, without mask. Send it when the payment is made from a company account.

requestExpiresAt
bodystring

Date and time when the payment request expires. Must be in the future. If not sent, the request does not expire.

txId
bodyarray<string>

Your identifiers for the payments, one per payment (only one for an immediate or single scheduled payment). Letters and numbers only, up to 35 characters (25 when the creditor has a Pix key), without repeats.

creditor●
bodyobject

Receiver (creditor) account details.

name●
bodystring

Creditor legal name.

personType●
bodystring

PESSOA_NATURAL or PESSOA_JURIDICA.

cpfCnpj●
bodystring

Creditor CPF or CNPJ.

accountNumber●
bodystring

Creditor account number.

accountIssuer●
bodystring

Creditor branch.

accountPixKey
bodystring

Creditor Pix key when applicable.

accountIspb●
bodystring

Creditor institution ISPB.

accountType●
bodystring

CACC | SVGS | TRAN.

debitor
bodyobject

Optional payer account hints when you already collected them.

accountNumber●
bodystring

Debtor account number.

accountIssuer●
bodystring

Debtor branch.

accountIspb●
bodystring

Debtor ISPB.

accountType●
bodystring

CACC | SVGS | TRAN.

schedule
bodyobject

Optional schedule. Send only one of single, daily, weekly, monthly, or custom. Start dates must be at least D+1; max 60 installments within two years from consent creation (per API contract).

single
bodyobject

One-shot future date.

date●
bodystring
daily
bodyobject

Daily recurrence.

startDate●
bodystring
quantity●
bodynumber
weekly
bodyobject

Weekly recurrence.

dayOfWeek●
bodystring
startDate●
bodystring
quantity●
bodynumber
monthly
bodyobject

Monthly recurrence.

dayOfMonth●
bodynumber
startDate●
bodystring
quantity●
bodynumber
custom
bodyobject

Explicit list of dates.

dates●
bodyarray

ISO date strings.

additionalInformation●
bodystring
curl --request POST \
  --url 'https://embedded-payment-manager.hml.linaob.com.br/api/v1/payments' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SEU_TOKEN>' \
  --data '{
  "redirectUri": "https://your-app.example.com/payments/return",
  "value": 150.5,
  "details": "Invoice 2024-001",
  "externalId": "ext-order-991",
  "cpfCnpj": "12345678909",
  "businessCnpj": "12345678000195",
  "requestExpiresAt": "2026-12-19T18:00:00Z",
  "txId": [
    "ext123",
    "ext1234"
  ],
  "creditor": {
    "name": "Acme Ltda",
    "personType": "PESSOA_JURIDICA",
    "cpfCnpj": "12345678000195",
    "accountNumber": "1234567",
    "accountIssuer": "0001",
    "accountPixKey": "cobranca@acme.com.br",
    "accountIspb": "12345678",
    "accountType": "CACC"
  },
  "debitor": {
    "accountNumber": "7654321",
    "accountIssuer": "0001",
    "accountIspb": "87654321",
    "accountType": "CACC"
  },
  "schedule": {
    "single": {
      "date": "2024-09-01"
    },
    "daily": {
      "startDate": "2024-09-01",
      "quantity": 2
    },
    "weekly": {
      "dayOfWeek": "QUARTA_FEIRA",
      "startDate": "2024-09-01",
      "quantity": 2
    },
    "monthly": {
      "dayOfMonth": 10,
      "startDate": "2024-09-01",
      "quantity": 2
    },
    "custom": {
      "dates": [
        "2024-08-23",
        "2024-09-26"
      ],
      "additionalInformation": "Custom schedule note"
    }
  }
}'

Response

201Payment request created. Redirect the browser to data.redirectUrl.
Response body
object
  • dataobjectrequired

    Created payment identifiers.

    • idstringrequired

      Payment request id (same as paymentLinkId on redirect callback).

    • redirectUrlstringrequired

      Hosted portal URL for the payer.

  • messagestring

    Human-readable message.

  • typestring

    success | error | warning | info.

  • statusCodeinteger· nullable

    Optional status inside envelope.

201 · Payment request created. Redirect the browser to data.redirectUrl.
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "redirectUrl": "https://embedded-payment-manager.hml.linaob.com.br/hpp/example-session"
  },
  "message": "",
  "type": "success",
  "statusCode": null
}

Company (PJ) payments

To receive a payment from a company account, send:

  • cpfCnpj: CPF of the person who will authorise the payment on behalf of the company.
  • businessCnpj: the company CNPJ.

Do not send the CNPJ in cpfCnpj.

{
  "redirectUri": "https://your-app.example.com/payments/return",
  "value": 150.5,
  "details": "Invoice 2024-001",
  "cpfCnpj": "12345678909",
  "businessCnpj": "12345678000195",
  "creditor": {
    "name": "Acme Ltda",
    "personType": "PESSOA_JURIDICA",
    "cpfCnpj": "11222333000181",
    "accountNumber": "1234567",
    "accountIssuer": "0001",
    "accountIspb": "12345678",
    "accountType": "CACC"
  }
}

Request expiration

Use requestExpiresAt to limit how long the payer has to start the payment, for example 2026-12-19T18:00:00Z. Without it, the request does not expire.

  • After this time, the payer can no longer continue the payment.
  • Once the payer is redirected to their bank, the deadline no longer applies.

Next steps