Originate Payments

TxB APIs allow Clients to originate payments and collections requests on-demand via US Fedwire, US ACH, and SWIFT. Our APIs are payment rail agnostic, so the same payment API can be used for any rail. Clients use these services to create customer facing payment applications (e.g., a checkout flow) or to power internal automated payment procedures (e.g., automatically paying a supplier once an invoice has been approved). After initiating a payment request, our payment status APIs allow Clients to track the progress of payment before debiting or crediting their accounts.

For context, read more about payment and collection request structures here.

Step by Step Guide (FX Payment)

Step 1 - Check the funding cost

Suppose you have a US Dollar deposit account at TxB and want to pay a European supplier in Euro (EUR 1300). Before making a thirteen-hundred Euro payment, you may want an estimated the funding cost of the payment in USD.

POST /v1/exchangeRates/query with this payload:

{
  "sourceCurrency": "USD",
  "paymentCurrency": "EUR",
  "amount": 1300,
  "amountType": "PAYMENTCURRENCY"
}

This query responds with the current USD->EUR conversion rate based on the Client's agreement with TxB. Let's say it responds by estimating the current cost of your payment to be $1,570.37, so you proceed with the payment.

Step 2 - Send paymentRequest

Now we can send the paymentRequest with POST /v1/payments/paymentRequest and the below request payload. We can include up to 500 individual payments in a single paymentRequest:

{
  "paymentRequestId": "custReq0123456789",

  // start of the fundingInfo object, which can
  // be deposit account at TxB or another bank

  "fundingInfoOrTemplateInfo": {
    "templateInfo": null,
    "fundingInfo": {
      "fundingAccount": {
        "accountNumber": "123456789011",
        "accountHolderName": "ACME.io Deposit Account",
        "relatedBanks": [
          {
            "bankRole": "HOLDER",
            "bic": "GSCRUS30"
          }
        ]
      }
      "fundingCurrency": "USD"
    }
  },

  // start of the payments array; each individual
  // payment has a unique paymentEndToEndId that
  // you can later query (for status)

  "payments": [
    {
      "paymentEndToEndId": "trackthispayment123",
      "payeeInfoOrTemplateInfo": {
        "payeeInfo": {
          "payeeAccount": {
            "accountNumber": "98876543210",
            "accountHolderName": "Supplier's Name"
            "relatedBanks": [
              {
                "bankRole": "HOLDER",
                "bic": "ROYCCAT2XXX"
              }
            ]
          }
        },
      },
      "amount": 1300
      "paymentCurrency": "EUR",
      "remittanceInfo": "I'd like to track this"
      ...
    }
  ]
}

Step 3 - Check the payment status

There are several different ways we can track a payment that is in progress or completed. Read below on the difference between a payment request and an individual payment.

First, we can confirm that the paymentRequest was accepted, meaning it has passed a technical and some business validation.

GET /v1/payments/paymentRequest/custReq0123456789 returns a "requestStatus": "ACCEPTED". If this paymentRequest were connected to a customer payment flow, we can tell the user it is now being processed. Note that this message is also passed back as a response to the original POST paymentRequest.

Now that we know the paymentRequest was successful, let's check the status of the individual payment within the request. This will tell you whether the payment is complete, is stuck for some reason (e.g., insufficient funds), or rejected (e.g., because the supplier's bank account number is not formatted correctly).

POST /v1/payments/status/query

with this request body:

{
  "idType": "PAYMENTENDTOENDID",
  "idValue": "custpid987654323"
}

returns the below, which tells you that the EUR currency market is closed right now and the payment will complete on the next business day:

{
  "paymentIdentifiers": {
    "paymentRequestId": "custReq0123456789",
    "paymentEndToEndId": "trackthispayment123",
    "gsUniquePaymentId": "gsuniquetracker123",
    ...
  },
  "paymentStatus": {
    "status": "PENDING",
    "statusReasonDescription": "Date warehoused"
    ...
  }
}

Step 4 - View full payment details

Finally, you can view full payment details which gives you both the status of the payment as well as other details like the associated FX rate.

POST /v1/payments/details/query

with this request body:

{
  "idType": "PAYMENTENDTOENDID",
  "idValue": "trackthispayment123"
}

returns the below, which tells you the payment has been completed:

{
  "paymentIdentifiers": {
    "paymentRequestId": "custReq0123456789",
    "paymentEndToEndId": "trackthispayment123",
    "gsUniquePaymentId": "gsuniquetracker123",
    ...
  },
  "paymentStatus": {
    "status": "SETTLED",
    "statusTime": "2020-12-01T16:52:42.279Z",
    ...
  },
  "creditorInfo": {...},
  "debtorInfo": {...}
  "fxInfo": {
    "paymentAmount": 1300,
    "paymentCurrency": "EUR",
    "sourceCurrency": "USD",
    "sourceAmount": 1580,
    "fxRate": 0.8228,
    "fxTimeStamp": "2020-12-01T02:52:42.279Z"
  }
}

Originate a collectionRequest

Our previous example showed how to transfer funds from a deposit account you own into an account you may not own, e.g., that of a supplier. We use a similar pattern for the reverse, to transfer funds into a deposit account you own from an account you may not own, e.g., that of a customer. Below is a summary of the elements.

For information about payments for UK & EU open banking, learn more here.