Send and cancel a wire payment
What you will learn
✅ How to originate an outbound wire transfer
✅ How to cancel an outbound wire transfer
✅ How to originate an outbound international wire transfer
If you are new to wires we recommend you read the wires overview 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 basics.
The tutorial uses these API endpoints:
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.
Before you begin
Make sure you have:
- Partner ID
- Master account number
- Registered the following webhook events:
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 |
Originate a outbound payment
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)
- Business function code: CTR
- Receiver routing number: 026009593 (Fedwire routing number)
- Beneficiary information:
- ID: D
- 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.
POST /wires/v1/payments
{
"accountNumber": "2342123458",
"businessFunctionCode": "CTR",
"receiverRoutingNumber": "026009593",
"beneficiary": {
"idCode": "D",
"identifier": "4289341024",
"name": "Miguel Nelson",
"address1": "250 Kuhn Highway",
"address2": "Grover, NC 28073"
},
"beneficiaryReference": "Invoice A523",
"amount": 10000,
"purpose": "Consulting Fee"
}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.
{
"id": "30423521-52e2-4329-b8f6-ada3011806f1",
"accountNumber": "2342123458",
"referenceId": "W21025MV1WA",
"direction": "Outbound",
"paymentType": "Transfer",
"source": "Api",
"status": "Created",
"posting": "Pending",
"amount": 10000,
"currency": "usd",
"purpose": "Consulting Fee",
"businessFunctionCode": "CTR",
"typeCode": "1000",
"senderRoutingNumber": "021214891",
"senderName": "Cross River Bank",
"senderReference": "W21025MV1WA",
"receiverRoutingNumber": "026009593",
"receiverName": "BK AMER NYC ",
"originatingFi": {
"idCode": "F",
"identifier": "021214891",
"name": "Cross River Bank",
"address1": "885 Teaneck Rd",
"address2": "Teaneck NJ 07666",
"address3": "US"
},
"originator": {
"idCode": "D",
"identifier": "2342123458",
"name": "Acme Co",
"address1": "400 Business Street",
"address2": "New York NY 10025"
},
"beneficiary": {
"idCode": "D",
"identifier": "4289341024",
"name": "Miguel Nelson",
"address1": "250 Kuhn Highway",
"address2": "Grover, NC 28073"
},
"beneficiaryReference": "Invoice A523",
"wasReversed": false,
"isInternational": false,
"createdAt": "2021-01-25T17:13:27.6503996-05:00",
"effectiveDate": "2021-01-25T00:00:00-05:00",
"originalPaymentId": "30423521-52e2-4329-b8f6-ada3011806f1",
"partnerId": "bf1baac0-1ae9-45ed-ade6-55baf1ae19a6",
"productId": "3941dec4-bd4b-4f3e-af7a-bc6d86b8a0dc",
"lastModifiedAt": "2021-01-25T17:13:27.6573998-05:00",
"postingCode": "OK"
}Confirm payment
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.
{
"id": "dab167cf-3d77-45ed-ad85-ada30118fc11",
"eventName": "Wire.Payment.Sent",
"status": "Pending",
"partnerId": "30dee145-b6a2-4058-8dc3-ac4000dee91f",
"createdAt": "2021-01-25T18:03:01.887-04:00",
"resources": [
"wires/v1/payments/30423521-52e2-4329-b8f6-ada3011806f1"
],
"details": []
}Cancel an outbound payment
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.
curl -X POST
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
'https://sandbox.crbcos.com/Wires/v1/payments/<p>Sample request</p>curl -X GET
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
'https://sandbox.crbcos.com/Wires/v1/payments/4d4c60b2-e073-409d-bc94-aff000043fcb/cancel'A successful API call returns a JSON response with the details of your canceled payment and shows a status value of Canceled.
{
"id": "30423521-52e2-4329-b8f6-ada3011806f1",
"accountNumber": "2342123458",
"referenceId": "W21025MV1WA",
"direction": "Outbound",
"paymentType": "Transfer",
"source": "Api",
"status": "Canceled",
"posting": "Posted",
"amount": 10000,
"currency": "usd",
"purpose": "Consulting Fee",
"businessFunctionCode": "CTR",
"typeCode": "1000",
"senderRoutingNumber": "021214891",
"senderName": "Cross River Bank",
"senderReference": "W21025MV1WA",
"receiverRoutingNumber": "026009593",
"receiverName": "BK AMER NYC ",
"originatingFi": {
"idCode": "F",
"identifier": "021214891",
"name": "Cross River Bank",
"address1": "885 Teaneck Rd",
"address2": "Teaneck NJ 07666",
"address3": "US"
},
"originator": {
"idCode": "D",
"identifier": "2342123458",
"name": "Acme Co",
"address1": "400 Business Street",
"address2": "New York NY 10025"
},
"beneficiary": {
"idCode": "D",
"identifier": "4289341024",
"name": "Miguel Nelson",
"address1": "250 Kuhn Highway",
"address2": "Grover, NC 28073"
},
"beneficiaryReference": "Invoice A523",
"wasReversed": false,
"isInternational": false,
"createdAt": "2021-01-25T17:13:27.6503996-05:00",
"canceledAt":"2021-01-25T19:04:10.7921285-05:00",
"effectiveDate": "2021-01-25T00:00:00-05:00",
"originalPaymentId": "30423521-52e2-4329-b8f6-ada3011806f1",
"partnerId": "bf1baac0-1ae9-45ed-ade6-55baf1ae19a6",
"productId": "3941dec4-bd4b-4f3e-af7a-bc6d86b8a0dc",
"lastModifiedAt": "2021-01-25T17:13:27.6573998-05:00",
"postingCode": "OK"
}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.
{
"id": "ff1b5fa5-ae3d-48eb-b389-b12901195195",
"eventName": "Wire.Payment.Canceled",
"status": "Pending",
"partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
"createdAt": "2021-03-04T12:04:15.003-05:00",
"resources": [
"wires/v1/payments/30423521-52e2-4329-b8f6-ada3011806f1"
],
"details": [
{
"paymentId": "30423521-52e2-4329-b8f6-ada3011806f1",
"accountNumber": "2342123458",
"direction": "Outbound",
"imad": null,
"omad": null,
"paymentType": "Transfer",
"purpose": "Consulting Fee",
"amount": "10000",
"clientIdentifier": null,
"originatingFiName": "34115033",
"originatingFiIdentifier": "021214891",
"originatorName": "Acme Co",
"originatorIdentifier": "2342123458",
"originatorAddress1": "400 Business Street",
"originatorAddress2": "",
"originatorAddress3": "New York NY 10025",
"beneficiaryFiName": null,
"beneficiaryFiIdentifier": null,
"beneficiaryName": "Miguel Nelson",
"beneficiaryIdentifier": "4289341024",
"beneficiaryAddress1": "250 Kuhn Highway",
"beneficiaryAddress2": "Grover, NC 28073"
"beneficiaryAddress3": null,
"beneficiaryReference": "Invoice A523",
"senderReference": "W21025MV1WA",
"originatorToBeneficiary1": null,
"originatorToBeneficiary2": null,
"originatorToBeneficiary3": null,
"originatorToBeneficiary4": null,
"coreTransactionId": "fa7ae94e-0fc0-4c4f-9680-b129011945d8"
}
]
}