{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/v2026.04/api-docs/tutorials/create-a-v2-payment","default":true,"active":false,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/api-docs/tutorials/create-a-v2-payment","default":false,"active":false,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/api-docs/tutorials/create-a-v2-payment","default":false,"active":true,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml","api-docs-@l10n/pt-BR/products/payments-direct-2/@v2025.11/api-docs/payments-direct-api/payments-direct-2-api.yml":"api-docs-@l10n/pt-BR/products/payments-direct-2/@v2025.11/api-docs/payments-direct-api/payments-direct-2-api.yml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Create a v2 payment","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-a-v2-payment","__idx":0},"children":["Create a v2 payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial, we'll step through the API calls required to create a B2B payment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In a B2B payment, you — a business or institution — are the payment originator and you're paying another business or institutional beneficiary."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While this tutorial focuses on paying a business beneficiary, the process is similar for paying an individual beneficiary."," ","To pay an individual beneficiary, specify their ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryIdentityId"]}," in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-payment"},"children":["Create payment"]}," step."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are three main steps for creating a payment where you are the originator:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-quote-collection"},"children":["Create a quote collection"]}," for a proposed payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-payment"},"children":["Create payment"]}," to begin the payment process."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#get-a-payment"},"children":["Get a payment"]}," to view details about the initiated payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must have the following items to be able to carry out the steps in this tutorial:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2025.11/api-docs/tutorials/request-an-access-token"},"children":["access token"]}," to access secured API endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtain the beneficiary ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityID"]}," using the Get identities v2 operation in the API reference."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-quote-collection","__idx":2},"children":["Create a quote collection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We'll begin by calling the Create quote collection operation to get a quote for the payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-payment","__idx":3},"children":["Create payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that we have the quote for the payment, it's time to create the payment using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To do this, we'll call the Create payment operation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-payment-request","__idx":4},"children":["Create payment request"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Prerequisites"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You must have the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," of the quote you want to accept from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-quote-collection-response"},"children":["create a quote"]}," response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You must have the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," of the beneficiary."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Construct the request body as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," : Set this value to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," you received in the Create quote collection response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryIdentityId"]}," : Set this value to the UUID associated with the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2025.11/api-docs/tutorials/building-v2-payment-request-body#beneficiaryidentityid"},"children":["beneficiary identity"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," : This example uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Invoice-123"]},". This is an optional sender-created reference (maximum 36 characters) for correlating payments with your own records and filtering in other API operations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purposeCode"]}," : This example uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYR"]}," to indicate that the purpose of this payment is payroll."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceOfCash"]}," : This example uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SVGS"]}," to indicate that the source of cash for this payment is savings."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"quoteId\": \"7ea3399c-1234-5678-8d8f-d320ea406630\",\n  \"beneficiaryIdentityId\": \"22222222-aaaa-2222-bbbb-222222222222\",\n  \"internalId\": \"Invoice-123\",\n  \"purposeCode\": \"PAYR\",\n  \"sourceOfCash\": \"SVGS\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-payment-response","__idx":5},"children":["Create payment response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A success response from the API contains the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," and other information you can use to monitor the status of the payment."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentId\": \"7ea3399c-1234-5678-8d8f-d320ea406630\",\n  \"initiatedAt\": \"2025-02-13T23:24:15.770Z\",\n  \"expiresAt\": \"2025-04-14T23:24:15.770Z\",\n  \"lastStateUpdatedAt\": \"2025-02-13T23:24:15.770Z\",\n  \"paymentState\": \"TRANSFERRING\",\n  \"originator\": {\n    \"internalId\": \"Invoice-123\",\n    \"sourceCountry\": \"US\",\n    \"sourceCurrency\": \"USD\",\n    \"sourceAmount\": 10000,\n    \"payin\": \"PRE_FUNDING\"\n  },\n  \"destination\": {\n    \"destinationAmount\": 203766.88,\n    \"destinationCountry\": \"MX\",\n    \"destinationCurrency\": \"MXN\",\n    \"beneficiaryIdentityId\": \"22222222-aaaa-2222-bbbb-222222222222\",\n    \"beneficiaryIdentityVersion\": 1,\n    \"beneficiaryIdentityNickName\": \"Successful Beneficiary\",\n    \"payout\": \"BANK\"\n  },\n  \"fxRate\": 20.4052,\n  \"adjustedExchangeRate\": {\n    \"adjustedRate\": 20.3422\n  },\n  \"fees\": [\n    {\n      \"totalFee\": 14,\n      \"feeCurrency\": \"USD\"\n    }\n  ],\n  \"purposeCode\": \"PAYR\",\n  \"transactionDetails\": {\n    \"paymentProduct\": \"PAYMENTS_DIRECT\",\n    \"flowType\": \"B2B\",\n    \"thirdPartyPayment\": false,\n    \"businessUseCase\": \"FIAT_TRANSFER\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-a-payment","__idx":6},"children":["Get a payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentbyid"},"children":["get payment by payment ID"]}," operation to look up the status of a payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-payment-request","__idx":7},"children":["Get payment request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," path parameter to specify the unique ID of the payment whose status you want to monitor."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"api-docs-@l10n/pt-BR/products/payments-direct-2/@v2025.11/api-docs/payments-direct-api/payments-direct-2-api.yml","operationId":"getPaymentById","parameters":{},"environments":{},"codeSamplesResolved":[{"lang":"shell","title":"curl","source":"curl -i -X GET \\\n  https://api.test.ripple.com/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \\\n  -H 'Authorization: Bearer <YOUR_JWT_HERE>'"},{"lang":"python","title":"Python","source":"import requests\n\npayment_id = \"7ea3399c-1234-5678-8d8f-d320ea406630\"\nurl = \"https://api.test.ripple.com/v2/payments/\" + payment_id\n\nheaders = {\"Authorization\": \"Bearer <YOUR_JWT_HERE>\"}\n\nresponse = requests.get(url, headers=headers)\n\ndata = response.json()\nprint(data)"}]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-payment-response","__idx":8},"children":["Get payment response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," field in the response for the current payment state."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentId\": \"7ea3399c-1234-5678-8d8f-d320ea406630\",\n  \"initiatedAt\": \"2025-02-13T23:24:15.770Z\",\n  \"expiresAt\": \"2025-04-14T23:24:15.770Z\",\n  \"lastStateUpdatedAt\": \"2025-02-13T23:24:15.770Z\",\n  \"paymentState\": \"INITIATED\",\n  \"originator\": {\n    \"internalId\": \"Invoice-123\",\n    \"sourceCountry\": \"US\",\n    \"sourceCurrency\": \"USD\",\n    \"sourceAmount\": 10000,\n    \"payin\": \"PRE_FUNDING\"\n  },\n  \"destination\": {\n    \"destinationAmount\": 203766.88,\n    \"destinationCountry\": \"MX\",\n    \"destinationCurrency\": \"MXN\",\n    \"beneficiaryIdentityId\": \"22222222-aaaa-2222-bbbb-222222222222\",\n    \"beneficiaryIdentityVersion\": 1,\n    \"beneficiaryIdentityNickName\": \"Successful Beneficiary\",\n    \"payout\": \"BANK\"\n  },\n  \"fxRate\": 20.4052,\n  \"fees\": [\n    {\n      \"totalFee\": 14,\n      \"feeCurrency\": \"USD\"\n    }\n  ],\n  \"purposeCode\": \"PAYR\",\n  \"payoutExecutionDetails\": {\n    \"paymentRailUsed\": \"ACH\",\n    \"payoutStartTime\": \"2025-02-13T23:25:00.000Z\",\n    \"payoutEndTime\": \"2025-02-13T23:34:54.000Z\",\n    \"trackingReferences\": [\n      {\n        \"referenceType\": \"IMAD\",\n        \"value\": \"20250213MMQFMP9N000123\",\n        \"displayName\": \"IMAD Number\",\n        \"description\": \"Input Message Accountability Data (IMAD) for Fedwire transfer tracking\"\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"payoutExecutionDetails"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payoutExecutionDetails"]}," is an optional field returned only by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/payments/{paymentId}"]},". It provides informational metadata about payout execution: the rail used (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRailUsed"]},"), timing (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payoutStartTime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payoutEndTime"]},"), and network-specific tracking references (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trackingReferences"]},"). Coverage varies by corridor and payout partner. Do not build required workflows that depend on its presence."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceType"]}," field on each tracking reference to identify what a value represents, for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IMAD"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OMAD"]}," for Fedwire transfers."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-state-transitions","__idx":9},"children":["Get state transitions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to getting the current state of a payment, you can also use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentstatetransitionsbyid"},"children":["get state transitions"]}," operation to see when the payment transitioned between states."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"api-docs-@l10n/pt-BR/products/payments-direct-2/@v2025.11/api-docs/payments-direct-api/payments-direct-2-api.yml","operationId":"getPaymentStateTransitionsById","parameters":{},"environments":{},"codeSamplesResolved":[{"lang":"shell","title":"curl","source":"curl -i -X GET \\\n  https://api.test.ripple.com/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630/states \\\n  -H 'Authorization: Bearer <YOUR_JWT_HERE>'"},{"lang":"python","title":"Python","source":"import requests\n\npayment_id = \"7ea3399c-1234-5678-8d8f-d320ea406630\"\nurl = \"https://api.test.ripple.com/v2/payments/\" + payment_id + \"/states\"\n\nheaders = {\"Authorization\": \"Bearer <YOUR_JWT_HERE>\"}\n\nresponse = requests.get(url, headers=headers)\n\ndata = response.json()\nprint(data)"}]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-state-transition-response","__idx":10},"children":["Get state transition response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examine the response to view the state transitions."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"stateTransitions\": [\n    {\n      \"updatedFrom\": \"QUOTED\",\n      \"updatedTo\": \"INITIATED\",\n      \"updatedAt\": \"2025-02-21T15:32:34.557Z\"\n    },\n    {\n      \"updatedFrom\": \"INITIATED\",\n      \"updatedTo\": \"VALIDATING\",\n      \"updatedAt\": \"2025-02-21T15:32:38.380Z\"\n    },\n    {\n      \"updatedFrom\": \"VALIDATING\",\n      \"updatedTo\": \"TRANSFERRING\",\n      \"updatedAt\": \"2025-02-21T15:32:49.552Z\"\n    },\n    {\n      \"updatedFrom\": \"TRANSFERRING\",\n      \"updatedTo\": \"COMPLETED\",\n      \"updatedAt\": \"2025-02-21T15:34:54.496Z\"\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Create a v2 payment","id":"create-a-v2-payment","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Create a quote collection","id":"create-a-quote-collection","depth":2},{"value":"Create payment","id":"create-payment","depth":2},{"value":"Create payment request","id":"create-payment-request","depth":3},{"value":"Create payment response","id":"create-payment-response","depth":3},{"value":"Get a payment","id":"get-a-payment","depth":2},{"value":"Get payment request","id":"get-payment-request","depth":3},{"value":"Get payment response","id":"get-payment-response","depth":3},{"value":"Get state transitions","id":"get-state-transitions","depth":2},{"value":"Get state transition response","id":"get-state-transition-response","depth":3}],"frontmatter":{"toc":{"enable":true,"maxDepth":2},"seo":{"title":"Create a v2 payment"}},"lastModified":"2026-04-01T23:09:00.000Z","isTranslationFallback":true,"pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/v2025.11/api-docs/tutorials/create-a-v2-payment","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}