Originating Wire Payments

In this tutorial we explore originating a wire payment from a master account. We will also register relevant webhooks to receive status updates on our payment. Before starting this tutorial, please make sure you have the following:

API credentials
Partner ID
Master Account Number

This tutorial also assumes you have already opened a master account. If not, please complete the Opening a Master Account tutorial prior to completing this tutorial.

Get an Access Token

Before calling the COS API you must first request an access token. Once the access token has been obtained it is recommended that it is cached for the lifetime of the token. If the API starts to return a 401 response code, it is likely that your token has expired and you need to obtain a new one. More details can be found here.

Register Webhooks

Webhooks allow us to receive notifications when certain events occur within COS. After we originate our wire payment in the step below, we will want to stay informed when it has been accepted by the Federal Reserve and an IMAD becomes available. For that you will need to call the webhook registration endpoint and indicate you wish to receive Wire.Payment.Sent events. An example of the webhook registration call is provided below.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Wire.Payment.Sent",
  "registrationType": "Push", 
  "callbackUrl": "https://cos.yourcompanysite.com/wire-events"
}

To learn more about webhook registrations click here. For a full listing of available wire webhook events click here.

Originating a Wire Payment

Wire payments can be used to send funds or non-value messages to other financial institutions via the FedWire Funds Service network. The type of message is defined by the businessFunctionCode. The receiverRoutingNumber field is the beneficiary financial institution's FedWire routing number. The beneficiary and beneficiaryReference fields refer to the individual or entity receiving the wire. For additional information on FedWire fields please see the reference section at the end of this tutorial.

In this scenario, Acme Co is sending a $100 wire payment to Bob Smith's account at Bank of America.

POST /wires/v1/payments
{
  "accountNumber": "2342123458",
  "businessFunctionCode": "CTR",
  "receiverRoutingNumber": "026009593",
  "beneficiary": {
    "idCode": "D",
    "identifier": "4289341024",
    "name": "Bob Smith",
    "address1": "123 Any Street",
    "address2": "Anywhere NY 12345"
  },
  "beneficiaryReference": "Invoice A523",
  "amount": 10000,
  "purpose": "Consulting Fee"
}

🚧
It is highly recommended that you include an idempotency key in your request header. This will provide duplicate protection in the event of a failure. Read more about idempotency keys here.

Here's a sample response body based on the above request:

{
  "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": "Bob Smith",
    "address1": "123 Any Street",
    "address2": "Anywhere NY 12345"
  },
  "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": "00000000-0000-0000-0000-000000000000",
  "productId": "00000000-0000-0000-0000-000000000000",
  "lastModifiedAt": "2021-01-25T17:13:27.6573998-05:00",
  "postingCode": "OK"
}

Payment Confirmation

After originating a payment, it will typically stay in a Pending or Hold status for minutes to hours. It may take up to a few days to transition in the case of weekends and bank holidays. A status of Hold indicates the payment is being reviewed by our Ops team and has not yet been approved for release to the Federal Reserve. A status of Pending lets you know that the payment is good to go, but has not yet been batched for release. Typically the batching process occurs a several times per day.

Given this, it is not recommended to poll for status updates. Instead the recommended method is to register for the Wire.Payment.Sent webhook event as we did earlier in this section. The Wire.Payment.Sent webhook is fired once the payment is released to the Fed and the Fed sends us an acknowledgment. This indicates the payment has been successfully accepted by the Federal Reserve and an IMAD is available.

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

{
  "id": "30423521-52e2-4329-b8f6-ada3011806f1",
  "accountNumber": "2342123458",
  "coreTransactionId": "420a4595-697c-4146-92b2-ada301180c55",
  "referenceId": "W21025MV1WA",
  "fedBatchId": "a886242c-6599-4348-a5eb-ada3011896c9",
  "fedBatchSequence": 1,
  "direction": "Outbound",
  "paymentType": "Transfer",
  "source": "API",
  "status": "Completed",
  "posting": "Posted",
  "amount": 10000,
  "currency": "usd",
  "purpose": "Consulting Fee",
  "imad": "20210914QMGFT015000255",
  "omad": "20210914B1QGC01R02693209141023",
  "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": "Bob Smith",
    "address1": "123 Any Street",
    "address2": "Anywhere NY 12345"
  },
  "beneficiaryReference": "Invoice A523",
  "receiptDate": "0125",
  "receiptTime": "1739",
  "wasReversed": false,
  "isInternational": false,
  "createdAt": "2021-01-25T17:13:27.6503996-05:00",
  "processedAt": "2021-01-25T17:33:27.6503996-04:00",
  "effectiveDate": "2021-01-25T00:00:00-04:00",
  "completedAt": "2021-01-25T17:39:45.8215996-04:00",
  "postedAt": "2021-01-25T17:13:29.66-04:00",
  "originalPaymentId": "30423521-52e2-4329-b8f6-ada3011806f1",
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "productId": "00000000-0000-0000-0000-000000000000",
  "lastModifiedAt": "2021-01-25T17:39:45.8215996-05:00",
  "postingCode": "OK"
}

Simulating an Inbound Payment

Our simulation endpoints allow partners to simulate an inbound wire payment to a deposit account or subledger. This can be done using the POST /v1/payments/simulations endpoint. In this scenario, we're simulating a refund transaction between an online streaming service, Stream247, and one of it's subscribers, John Wick. Stream247 wants to refund John Wick by sending him $19.99 via a wire payment from their JP Morgan Chase account. Here's what the request to the simulation endpoint would look like:

{
  "accountNumber": "2846838676",
  "originator": {
    "idCode": "D",
    "identifier": "4236598541",
    "name": "Stream247",
    "address1": "555 Business Rd",
    "address2": "Anywhere NY 11101"
  },
  "businessFunctionCode": "CTR",
  "senderRoutingNumber": "021000021",
  "senderDiName": "JP Morgan Chase",
  "originatorFi": {
    "idCode": "F",
    "identifier": "021000021",
    "name": "JP Morgan Chase"
  },
  "beneficiaryReference": "Refund Dec2021",
  "amount": 1999
}

A successful response from COS would provide the details for the inbound wire. Here's an example response:

{
  "id": "e68e32c3-a475-4d0b-a6d8-ae3c01186ff4",
  "accountNumber": "2846838676",
  "referenceId": "W2204571AT5",
  "direction": "Inbound",
  "paymentType": "Transfer",
  "source": "Api",
  "status": "Hold",
  "posting": "Pending",
  "amount": 1999,
  "currency": "usd",
  "purpose": "TEST",
  "imad": "1563371856856662630811",
  "omad": "942955532798176168895701363106962410",
  "businessFunctionCode": "CTR",
  "typeCode": "1000",
  "senderRoutingNumber": "021000021",
  "senderName": "JP MORGAN CHASE",
  "senderReference": "TEST",
  "receiverRoutingNumber": "021214891",
  "receiverName": "CROSS RIVER BANK2",
  "originatingFi": {
    "idCode": "F",
    "identifier": "021000021",
    "name": "JP Morgan Chase"
  },
  "originator": {
    "idCode": "D",
    "identifier": "4236598541",
    "name": "Stream247",
    "address1": "555 Business Rd",
    "address2": "Anywhere NY 11101"
  },
  "beneficiaryFi": {
    "idCode": "F",
    "identifier": "021000021",
    "name": "CROSS RIVER BANK",
    "address1": "400 KELBY STREET",
    "address2": "FORT LEE, NJ",
    "address3": "US"
  },
  "beneficiary": {
    "idCode": "D",
    "identifier": "2846838676",
    "name": "JOHN WICK",
    "address1": "55 VALHALLA RD",
    "address2": "",
    "address3": "VALHALLA NY 10572 US"
  },
  "beneficiaryReference": "REFUND DEC2021",
  "receiptDate": "0214",
  "receiptTime": "1201",
  "wasReversed": false,
  "isInternational": false,
  "createdAt": "2022-02-14T12:01:02.460748-05:00",
  "effectiveDate": "2022-02-14T00:00:00-05:00",
  "originalPaymentId": "e68e32c3-a475-4d0b-a6d8-ae3c01186ff4",
  "partnerId": "f03ff044-8883-4939-9d22-ade301661897",
  "productId": "9b8490c9-ccac-4f7d-8b49-ae3800e6b418",
  "lastModifiedAt": "2022-02-14T12:01:02.4967164-05:00",
  "postingCode": "OK"
}

If you are subscribed to the Wire.Payment.Received then you would receive an event which includes the payment ID in the resources array (which will be the same as the ID you received in the response to your simulation request):

{
  "id": "3809b97e-58dc-4082-bc64-ae3c01188e1c",
  "eventName": "Wire.Payment.Received",
  "status": "Pending",
  "partnerId": "f03ff044-8883-4939-9d22-ade301661897",
  "createdAt": "2022-02-14T12:01:28.197-05:00",
  "resources": [
    "wires/v1/payments/e68e32c3-a475-4d0b-a6d8-ae3c01186ff4"
  ],
  "details": []
}

You can use the payment ID from the event resources array with GET /v1/payments/{id} to query the payment details:

{
  "id": "e68e32c3-a475-4d0b-a6d8-ae3c01186ff4",
  "accountNumber": "2846838676",
  "coreTransactionId": "d4849a57-d028-4d8a-8622-ae3c0118701e",
  "referenceId": "W2204571AT5",
  "direction": "Inbound",
  "paymentType": "Transfer",
  "source": "Api",
  "status": "Completed",
  "posting": "Posted",
  "amount": 1999,
  "currency": "usd",
  "purpose": "TEST",
  "imad": "1563371856856662630811",
  "omad": "942955532798176168895701363106962410",
  "businessFunctionCode": "CTR",
  "typeCode": "1000",
  "senderRoutingNumber": "021000021",
  "senderName": "JP MORGAN CHASE",
  "senderReference": "TEST",
  "receiverRoutingNumber": "021214891",
  "receiverName": "CROSS RIVER BANK2",
  "originatingFi": {
    "idCode": "F",
    "identifier": "021000021",
    "name": "JP Morgan Chase"
  },
  "originator": {
    "idCode": "D",
    "identifier": "4236598541",
    "name": "Stream247",
    "address1": "555 Business Rd",
    "address2": "Anywhere NY 11101"
  },
  "beneficiaryFi": {
    "idCode": "F",
    "identifier": "021000021",
    "name": "CROSS RIVER BANK",
    "address1": "400 KELBY STREET",
    "address2": "FORT LEE, NJ",
    "address3": "US"
  },
  "beneficiary": {
    "idCode": "D",
    "identifier": "2846838676",
    "name": "JOHN WICK",
    "address1": "55 VALHALLA RD",
    "address2": "",
    "address3": "VALHALLA NY 10572 US"
  },
  "beneficiaryReference": "REFUND DEC2021",
  "receiptDate": "0214",
  "receiptTime": "1201",
  "wasReversed": false,
  "isInternational": false,
  "createdAt": "2022-02-14T12:01:02.46-05:00",
  "processedAt": "2022-02-14T12:01:02.603-05:00",
  "effectiveDate": "2022-02-14T00:00:00-05:00",
  "completedAt": "2022-02-14T12:01:02.69-05:00",
  "postedAt": "2022-02-14T12:01:02.69-05:00",
  "originalPaymentId": "e68e32c3-a475-4d0b-a6d8-ae3c01186ff4",
  "partnerId": "f03ff044-8883-4939-9d22-ade301661897",
  "productId": "9b8490c9-ccac-4f7d-8b49-ae3800e6b418",
  "lastModifiedAt": "2022-02-14T12:01:02.6896842-05:00",
  "postingCode": "OK"
}

Reference

Field Name	Description
accountNumber	This is the COS account number being used to originate the wire payment.
originatorIdCode	This is the identifier code for party sending the wire. For outbound payments where originator details are submitted with your payment request, the value of this field should be "D". Otherwise, COS will automatically populate this field.
originatorIdentifier	This is the identifier for the party sending the wire. For outbound payments where originator details are submitted with your payment request, this would be your COS account. Otherwise, COS will automatically populate this field.
businessFunctionCode	This describes the business purpose of the wire transfer. The most common type is CTR (customer wire transfer where the beneficiary is not a bank). For a full list of codes and descriptions, visit the wires reference section.
receiverRoutingNumber	This is the Fedwire routing number of the beneficiary’s (receiver’s) bank. You can use the ABA Directory to look up a financial institution’s routing number.
intermediaryFiIdCode	This is the identifier code for intermediary bank involved with your wire payment transaction. Not all wire transfers use an intermediary bank.
intermediaryFiIdentifier	This is the identifier for the intermediary bank involved with your wire payment transaction. Not all wire transfers use an intermediary bank.
beneficiaryFiIdCode	This is the identifier code for the bank receiving the wire. For outbound payments, this would generally be "F" to indicate the bank's Fed routing number. This field is optional for domestic wires as COS will automatically use the banking information for the value entered into the receiverRoutingNumber field.
beneficiaryFiIdentifier	This is the identifier for the bank receiving the wire. For outbound payments, this would generally be the bank's Fed routing number. This field is optional for domestic wires as COS will automatically use the banking information for the value entered into the receiverRoutingNumber field.
beneficiaryIdCode	This is the identifier code for party receiving the wire. For outbound payments, this would generally be "D" to indicate a deposit account.
beneficiaryIdentifier	This is the identifier for the party receiving the wire. For outbound payments, this would generally be the beneficiary's account number.
beneficiaryReference	This is an optional field which can be used to relay additional information to the beneficiary
originatorToBeneficiary	This is an optional field which can be used to relay additional information to the beneficiary. There are 4 originator to beneficiary fields available.
amount	The amount of the wire transfer.
purpose	This provides the reason for the wire transfer and is for internal use only. The data in this field is internal only does not get included with the outgoing FedWire message.
clientIdentifier	Optional field used for idempotency handling. See this page for additional information.
imad	Input Messaging Accountability Data: A combination of a date, source identifier, and sequence number assigned to a Fedwire message when it is processed by the Federal Reserve Bank Funds Transfer application.
omad	Output Messaging Accountability Data: A combination of a date, destination identifier, and sequence number assigned to a Fedwire message when it is processed by the Federal Reserve Bank Funds Transfer application.

Additional reference information can be found on the Wires API Reference page.