How to originate an outbound wire payment

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.

In this tutorial, you'll learn how to

Register the relevant webhooks

Originate an outbound wire transfer

Cancel an outbound wire transfer

The tutorial uses this API endpoint:

API 

Description

POST /wires/v1/payments00000

Sends an outbound wire transfer

POST /wires/v1/payments/{id}/cancel

Cancels a wire transfer
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

Before you begin

Make sure you have

1. Register the relevant webhook events

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.

2. Originate a Wire Payment

a. To originate the wire transfer

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 code: 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. Read more about idempotency keys here.

Copy

POST /wires/v1/payments request

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.

Copy

POST /wires/v1/payments response

{
  "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"
}

3. Payment confirmation

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.

Copy

Sample Wire.Payment.Sent event

{
  "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": []
}

4. Cancel an outbound wire transfer

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.

Copy
POST /wires/v1/payments/{id}/cancel request
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.

Copy
POST /wires/v1/payments/{id}/cancel response
{
  "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.

Copy
Sample Wire.Payment.Canceled event
{
  "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"
    }
  ]
}