Pular para o conteúdo

Criar um pagamento

Corredores compatíveis

Para conhecer os corredores de pagamento compatíveis, consulte Payout network.

Neste tutorial, você percorrerá as etapas necessárias para criar um pagamento usando a API do Payments Direct com o novo endpoint de pagamentos v3:

  1. Criar uma coleção de cotações para um pagamento proposto.
  2. Escolher uma cotação da coleção.
  3. Criar um pagamento usando a operação de pagamentos v3, incluindo:
    • beneficiaryIdentityId (ID da identidade do pagamento do beneficiário)
    • beneficiaryFinancialInstrumentId (ID do instrumento financeiro / método de pagamento do beneficiário)
    • (Opcionalmente) originatorIdentityId (ID da identidade do pagamento do ordenante, para pagamentos de terceiros)
  4. Obter as transições de estado do pagamento para confirmar que ele chegou a COMPLETED.

Para saber mais sobre identidades do pagamento e instrumentos financeiros, consulte Identidades do pagamento e Instrumentos financeiros.

Antes de começar

Para seguir este tutorial, você deve ter:

  • Acesso ao ambiente UAT da API do Payments Direct.
  • Um token de acesso OAuth2 válido com escopos para cotações e pagamentos.
  • Ao menos uma identidade de ordenante (e, opcionalmente, uma identidade para fluxos de ordenante de terceiros).
  • Ao menos uma identidade de beneficiário e um ou mais instrumentos financeiros para esse beneficiário.

Etapa 1: Criar uma coleção de cotações

Primeiro, solicite uma coleção de cotações que descreva quanto o seu beneficiário receberá, a taxa de câmbio, as tarifas e quando a cotação expira.

Neste exemplo, um remetente está enviando 10.000 USD a um beneficiário no México, que receberá MXN em uma conta bancária.

Endpoint

POST /v3/quotes/quote-collection

Parâmetros do corpo da requisição

No mínimo, forneça:

  • quoteAmount – O valor que você deseja cotar.
  • quoteAmountType – Se quoteAmount é um valor de origem ou de destino (por exemplo, SOURCE_AMOUNT).
  • sourceCurrency / destinationCurrency – As moedas de envio e de recebimento.
  • destinationCountry – O país do beneficiário (código ISO 3166-1 alfa-2), obrigatório para um payout em moeda fiduciária. sourceCountry, o país do ordenante, é opcional.
  • paymentRail – Opcional. Solicita uma cotação para apenas um payment rail. Omita o campo para receber uma cotação para cada payment rail disponível para o corredor. Consulte Referência de payment rails.
  • payinCategory – Como você financia o pagamento (PRE_FUNDING, CREDIT_FUNDING ou JIT_FUNDING). Para mais detalhes, consulte Modelo de financiamento.

Exemplo de requisição

curl -i -X POST \
  https://api.test.ripple.com/v3/quotes/quote-collection \
  -H "Authorization: Bearer <YOUR_JWT_HERE>" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteAmount": 10000,
    "quoteAmountType": "SOURCE_AMOUNT",
    "sourceCurrency": "USD",
    "destinationCurrency": "MXN",
    "sourceCountry": "US",
    "destinationCountry": "MX",
    "payinCategory": "PRE_FUNDING"
  }'

Exemplo de resposta (truncado)

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    {
      "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "quoteStatus": "ACTIVE",
      "quoteAmountType": "SOURCE_AMOUNT",
      "sourceAmount": 10000,
      "destinationAmount": 204533.30,
      "sourceCurrency": "USD",
      "destinationCurrency": "MXN",
      "destinationCountry": "MX",
      "payinCategory": "PRE_FUNDING",
      "paymentRail": "SPEI",
      "adjustedExchangeRate": {
        "adjustedRate": 20.4136
      },
      "fees": [
        {
          "totalFee": 14,
          "feeCurrency": "USD"
        }
      ],
      "createdAt": "2025-11-13T22:44:34.711Z",
      "expiresAt": "2025-11-13T22:59:34.767Z"
    }
  ]
}
O que verificar
  • quoteStatus deve ser ACTIVE.
  • Anote o quoteId que você deseja usar; você o passará para a operação Criar pagamento.

Etapa 2: Escolher uma cotação

Uma coleção de cotações contém uma cotação para cada payment rail disponível para o corredor, e cada cotação indica o seu payment rail. O México oferece um único rail, SPEI, portanto esta coleção contém uma única cotação. Em um corredor com vários rails, a lógica da sua aplicação deve:

  1. Iterar por quotes[] na resposta.
  2. Aplicar os seus critérios (por exemplo, o payment rail, as tarifas ou a taxa de câmbio).
  3. Selecionar um único quoteId para a etapa Criar pagamento.

O payment rail indicado na cotação que você escolher é o rail que o pagamento usa.

Para o restante deste tutorial, vamos supor que você selecione:

quoteId = 7ea3399c-1234-5678-8d8f-d320ea406630

Etapa 3: Criar um pagamento com a operação de pagamentos v3

Depois de selecionar uma cotação, você pode criar um pagamento usando a operação de pagamentos v3. É aqui que você conecta:

  • A cotação (quoteId)
  • A identidade do beneficiário (beneficiaryIdentityId)
  • O instrumento financeiro do beneficiário (beneficiaryFinancialInstrumentId)
  • (Opcionalmente) a identidade do ordenante (originatorIdentityId), caso você esteja enviando em nome de um cliente

O beneficiaryFinancialInstrumentId identifica a conta que recebe os fundos. Cada identidade tem um instrumento financeiro ativo, portanto este é o instrumento atualmente vinculado à identidade do beneficiário.

Rótulos de pagamento

paymentLabels são strings simples que você pode usar para categorizar e pesquisar pagamentos. Um padrão comum é armazenar pares chave=valor.

Por exemplo:

"paymentLabels": [
  "customerSegment=PREMIUM",
  "invoiceNumber=INV-2025-0615"
]

Esses rótulos podem ser atualizados posteriormente por meio da operação Update payment labels.

Endpoint

POST /v3/payments

Campos obrigatórios e opcionais

Campos obrigatórios principais na requisição de pagamento v3:

  • quoteId – O quoteId da cotação que você selecionou.
  • beneficiaryIdentityId – O token de identidade do beneficiário.
  • beneficiaryFinancialInstrumentId – O token do instrumento financeiro da conta de pagamento do beneficiário.

Opcionais, mas comumente usados:

  • originatorIdentityId – Inclua para pagamentos de terceiros em que você envia em nome de uma empresa ou instituição. Omita (ou use a sua própria identidade) quando você for o ordenante.
  • receiverRelationship – Relação entre o ordenante e o beneficiário (por exemplo, FAMILY, SUPPLIER).
  • paymentMemo – Memo de texto livre usado para conciliação; não é armazenado na PII.
  • paymentLabels – Rótulos de string definidos pela aplicação para agrupar e categorizar pagamentos (por exemplo, customerSegment=PREMIUM). Os rótulos são armazenados como strings simples; uma convenção comum é usar pares chave=valor.
  • Outros campos opcionais, como internalId, purposeCode e sourceOfCash, podem estar disponíveis dependendo da sua configuração.
Transações diretas vs. pagamentos de terceiros
  • Transação direta: Você é o ordenante; o originatorIdentityId é omitido ou definido como a sua própria identidade.
  • Terceiros: Você envia em nome de um cliente; o originatorIdentityId deve ser definido como o token de identidade desse cliente.

Exemplos de requisição

Vamos mostrar lado a lado os exemplos de transação direta e de terceiros.

Neste exemplo, você é o ordenante. Você omite o originatorIdentityId (ou usa a sua própria identidade).

curl -i -X POST \
  https://api.test.ripple.com/v3/payments \
  -H "Authorization: Bearer <YOUR_JWT_HERE>" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c",
    "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1",
    "receiverRelationship": "SUPPLIER",
    "paymentMemo": "INVOICE 2025-0615",
    "paymentLabels": [
      "customerSegment=PREMIUM",
      "invoiceNumber=INV-2025-0615"
    ]
  }'

Exemplo de resposta

Em caso de sucesso, a API retorna uma resposta 201 com detalhes do pagamento e um paymentId que você pode usar para monitorá-lo. O paymentId tem o mesmo valor do quoteId que você aceitou, porque um pagamento é identificado pela sua cotação.

{
  "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "paymentState": "INITIATED",
  "receiverRelationship": "SUPPLIER",
  "paymentMemo": "INVOICE 2025-0615",
  "paymentLabels": [
    "customerSegment=PREMIUM",
    "invoiceNumber=INV-2025-0615"
  ],
  "originator": {
    "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11",
    "sourceCurrency": "USD",
    "sourceAmount": "10000.00",
    "sourceCountry": "US"
  },
  "destination": {
    "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c",
    "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1",
    "destinationCurrency": "MXN",
    "destinationAmount": "204533.30",
    "destinationCountry": "MX"
  },
  "fees": {
    "totalFeesAmount": "14.00",
    "totalFeesCurrency": "USD"
  },
  "createdAt": "2025-03-15T10:23:45Z",
  "initiatedAt": "2025-03-15T10:23:45Z",
  "expiresAt": "2025-03-15T10:28:45Z"
}
O valor-chave a capturar é:

paymentId = 7ea3399c-1234-5678-8d8f-d320ea406630

Você o usará nas etapas posteriores.

Pagamentos financiados via JIT

Se você usou payinCategory: JIT_FUNDING na sua cotação, o pagamento estará inicialmente no estado AWAITING_FUNDING em vez de INITIATED. A resposta incluirá um timestamp jitFundingExpiresAt. Você deve transferir os recursos necessários para a sua conta no ledger da Ripple antes desse horário para que o pagamento prossiga. Se o prazo passar sem o financiamento, o pagamento expira e você deve criar uma nova cotação e um novo pagamento.

Etapa 4: Obter um pagamento por ID (opcional, mas recomendado)

Para verificar o status atual de um pagamento ou recuperar os seus detalhes, chame a operação Get payment by ID.

Endpoint

GET /v3/payments/{paymentId}

Exemplo de requisição

curl -i -X GET \
  https://api.test.ripple.com/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \
  -H "Authorization: Bearer <YOUR_JWT_HERE>"

Exemplo de resposta (truncado)

{
  "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "initiatedAt": "2025-03-15T10:23:45Z",
  "expiresAt": "2025-03-15T10:28:45Z",
  "lastStateUpdatedAt": "2025-03-15T10:24:15Z",
  "paymentState": "TRANSFERRING",
  "originator": {
    "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11",
    "sourceCountry": "US",
    "sourceCurrency": "USD",
    "sourceAmount": 10000,
    "payin": "PRE_FUNDING"
  },
  "destination": {
    "destinationAmount": 204533.30,
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c",
    "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1",
    "selectedPaymentRail": "SPEI"
  }
}
Você pode usar este endpoint para:
  • Inspecionar o paymentState para ver em que ponto do ciclo de vida o pagamento está.
  • Persistir a resposta para as suas próprias auditorias ou painéis internos.

Etapa 5: Obter as transições de estado para confirmar a conclusão

Para ver como um pagamento se moveu pelo seu ciclo de vida, especialmente para confirmar que ele chegou a COMPLETED, use a operação Get state transitions.

Endpoint

GET /v3/payments/{paymentId}/states

Exemplo de requisição

curl -i -X GET \
  https://api.test.ripple.com/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630/states \
  -H "Authorization: Bearer <YOUR_JWT_HERE>"

Exemplo de resposta

{
  "stateTransitions": [
    {
      "updatedFrom": "QUOTED",
      "updatedTo": "INITIATED",
      "updatedAt": "2025-03-15T10:23:45Z"
    },
    {
      "updatedFrom": "INITIATED",
      "updatedTo": "VALIDATING",
      "updatedAt": "2025-03-15T10:23:47Z"
    },
    {
      "updatedFrom": "VALIDATING",
      "updatedTo": "TRANSFERRING",
      "updatedAt": "2025-03-15T10:23:55Z"
    },
    {
      "updatedFrom": "TRANSFERRING",
      "updatedTo": "COMPLETED",
      "updatedAt": "2025-03-15T10:25:12Z"
    }
  ]
}

A sua aplicação pode:

  • Consultar este endpoint por polling até que o estado mais recente seja COMPLETED, ou
  • Usar um mecanismo de eventos/webhook, se disponível no seu ambiente.
Interpretando as transições de estado
  • Cada objeto em stateTransitions[] registra uma mudança em paymentState.
  • Considere o pagamento concluído com sucesso quando o valor updatedTo da última transição for COMPLETED.
  • Outros estados terminais podem incluir FAILED ou RETURNED, dependendo do comportamento do corredor e da rede de pagamento.
  • Se o pagamento for rejeitado ou devolvido, você verá estados terminais como DECLINED ou RETURNED em vez de COMPLETED.

Tratamento de erros

Os erros comuns neste fluxo de trabalho incluem:

  • 400 Bad Request – corpo da requisição malformado, campos obrigatórios faltando ou combinações inválidas (por exemplo, moeda/trilho incompatíveis).
  • 404 Not Found – coleção de cotações, cotação ou ID de pagamento inexistente.
  • 409 Conflict – mudanças conflitantes ou restrições de negócio (por exemplo, uso de uma identidade ou instrumento inativo).
  • 422 Unprocessable Entity – o pagamento não pode prosseguir devido a falhas de validação específicas do corredor.
  • 500 Internal Server Error – problemas inesperados no servidor; tente novamente ou entre em contato com o suporte se persistir.

Os erros relacionados a pagamentos são retornados em um schema de erro padrão que inclui:

  • code – código de erro legível por máquina
  • title – resumo curto legível por humanos
  • description – explicação mais detalhada e dicas de correção

Consulte a seção Erros da API da documentação da API do Payments Direct para obter uma lista completa de códigos de erro.

Resumo e próximos passos

Neste tutorial, você:

  1. Criou uma coleção de cotações para precificar um pagamento internacional.
  2. Selecionou uma cotação e usou o seu quoteId para criar um pagamento com a operação v3, incluindo:
    • beneficiaryIdentityId
    • beneficiaryFinancialInstrumentId
    • O originatorIdentityId opcional para pagamentos de terceiros
    1. Recuperou o pagamento e, em seguida, as suas transições de estado para confirmar que ele chegou a COMPLETED.

Em seguida, você pode:

Fetch a quote collection

Get ledger balances and transactions