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",
"requestLevel": {
// start of the fundingInfo object, which can
// be deposit account at TxB or another bank
"fundingSource": {
"fundingAccount": {
"accountInfo": {
"accountHolderName": "ACME.io Deposit Account",
"accountIdentifier": {
"accountNumber": "123456789011"
},
"bankIdentifier": {
"bic": "GSCRUS30"
}
}
},
"fundingCurrency": "USD"
},
"routingPreferences": {
"paymentTypePreference": "WIRE"
}
},
// start of the payments array; each individual
// payment has a unique paymentEndToEndId that
// you can later query (for status)
"payouts": [
{
"paymentEndToEndId": "trackthispayment123",
"corePayoutInfo": {
"payeeAccount": {
"accountInfo": {
"accountHolderName": "Payee Name",
"accountIdentifier": {
"accountNumber": "98876543210"
},
"bankIdentifier": {
"bic": "ROYCCAT2XXX"
}
}
},
"requestedPaymentDate": "2023-06-01",
"paymentCurrency": "EUR",
"amount": 1300,
"messagesFromOriginator": {
"paymentPurpose": "payment purpose text..",
"remittanceInfo": {
"unstructuredRemittance": [
"remittance info text..."
]
}
}
},
"otherPayoutInfo": {
"fxPayoutLevel": {
"amountType": "PAYMENT"
}
}
}
]
}Step 3 - Check the payment status and details
First, we can confirm that the paymentRequest was accepted, meaning it has passed technical and some business validation.
The response to the original POST paymentRequest in the previous step returns a "requestStatus": "ACCEPTED". If this paymentRequest were connected to a customer payment flow, we can tell the user it is now being processed.
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 /v2/payments/query
with this request body:
{
"idType": "PAYMENTENDTOENDID",
"idValue": "trackthispayment123"
}returns the below, which gives you both the status of the payment as well as other details like the associated FX rate:
[
{
"identifiers": {
"paymentRequestId": "custReq0123456789",
"paymentEndToEndId": "trackthispayment123",
"gsUniquePaymentId": "gsuniquetracker123",
...
"railReferenceId": {
"rail": "SWIFT",
"railId": "6a797e06-8588-4000-8167-870decc18cfe"
}
},
"paymentStatus": {
"status": "SETTLED",
"statusTime": "2023-06-01T16:10:00.109Z",
"statusReasonCode": null,
"statusReasonDescription": null
},
"paymentExecutedValueDate": "2023-06-01",
"amount": 1300,
"amountType": "PAYMENT",
"paymentCurrency": "EUR",
"fxInfo": {
"paymentAmount": 1300,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 1580,
"fxRate": ...,
...
},
...
}
]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.
| Elements of a collectionRequest | # per collectionRequest | Description |
|---|---|---|
collectionRequestId | 1 | The unique identifier of your collectionRequest. You can query this later to get status |
depositSource object | 1 | The deposit account into which you want to pull funds. Must be a TxB deposit account |
collections array | 1- ~500 | The deposit account from which you want to pull money. Is typically a non-TxB deposit account owned by someone else. You can originate multiple collections with a single request |
railSpecificRequestLevel | Optional | For certain payment rails, like ACH, some additional info like 'sec' code is required |
Track balances and transactions
arrow_forwardReview how to keep track of your deposit account balances, completed payments, and other transactions
For information about payments for UK & EU open banking, learn more here.
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.