Originate a payment
In this tutorial, you'll learn how to:
✅ Originate an outbound wire transfer
✅ Cancel an outbound wire transfer
✅ Originate an outbound international wire transfer
If you are new to wire transfers we recommend you read our documentation before starting this tutorial.
The tutorial assumes you have a knowledge of APIs and how they work. For more information on sending API calls, see the API overview page.
The tutorial uses this API endpoint:
API | Description |
|---|---|
Sends an outbound wire transfer | |
Cancels a wire transfe |
IMPORTANT
- Do not poll the APIs for status updates and reconciliation purposes.
- Incorporate webhooks into the payment reconciliation process.
The tutorial uses these webhooks:
Webhook | Description |
|---|---|
Wire.Payment.Sent | Outbound wire has been transmitted to the Federal Reserve and has been successfully acknowledged. IMAD number is now available. |
Wire.Payment.Received | Inbound wire payment received successfully. |
Wire.Payment.Rejected | Outbound wire could not be processed due to compliance reasons or was rejected by the Federal Reserve. |
Wire.Payment.Canceled | Outbound wire transfer was canceled |
Make sure you have
- Partner ID
- Master account number
To receive the webhook events for this tutorial you need to register each specific webhook event type. Once you are registered, the event objects are sent to the registered URLs.
The event object contains a list of resource identifiers used to download details of each event.
Call POST /wires/v1/payments to send the $100 wire transfer. In this example, we supply values for the following required attributes:
- Account number: 2342123458 (originator's account number)
- Receiver routing number: 026009593 (Fedwire routing number)
- Beneficiary information:
- Identifier: 4289341024 (beneficiary's account number)
- Name: Miguel Nelson
- Amount: 10000 (amount in USD with no decimal point between the dollars and cents)
- Purpose: Consulting Fee
IMPORTANT We strongly recommend that you include an idempotency key in your request header to provide duplicate protection should the payment fail. Read more about idempotency keys here.
A successful API call returns a JSON response with the details of your originated payment: Acme Co, as the originator, sent a wire transfer direction: Outbound, in the amount of $100 reflected in amount as 10000, to Miguel Nelson, the receiver, whose account is at BK AMER NYC.
After originating the payment, its status changes to Pending or Hold for up to several hours.
- A Pending status lets you know that the payment request is created but has not been batched for release to the Federal Reserve. The batching process occurs several times a day.
- A Hold status indicates that the payment request is in review and has not yet been approved for release to the Federal Reserve.
Acknowledgement of the payment by the Fed triggers the Wire.Payment.Sent event. This indicates successful acceptance of the payment by the Federal Reserve and the availability of an IMAD.
The payment ID provided in the response body of the payment origination request (id) appears in the resources object of the wire.Payment.Sent event for ease of identification. In this case the payment ID is 30423521-52e2-4329-b8f6-ada3011806f1.
You can cancel a wire transfer if it has not reached batch status, which tells you that the payment is in the process of being released to the Fed. Specifically, you can cancel a wire transfer with a pending or hold status.
Call POST /wires/v1/payments/{id}/cancel . For the id attribute use the payment ID returned in the response to POST /wires/v1/payments. In our case, we'll use 30423521-52e2-4329-b8f6-ada3011806f1.
A successful API call returns a JSON response with the details of your canceled payment and shows a status value of Canceled.
The Wire.Payment.Canceled event also communicates the payment cancellation, just like the response to calling POST /wires/v1/payments/{id}/cancel.
The payment ID provided in the response body of the payment origination request (id) appears in the details object of the wire.Payment.Canceled event for ease of identification, along with other transfer details. In this case the payment ID is 30423521-52e2-4329-b8f6-ada3011806f1. Note that the Pending status refers to the webhook and not the payment.
