menu

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.

Elements of a collectionRequest# per collectionRequestDescription
collectionRequestId1The unique identifier of your collectionRequest. You can query this later to get status
depositAccountInfo object1The deposit account into which you want to pull funds. Must be a TxB deposit account
collections array1- ~500The 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
railSpecificInfoOptionalFor certain payment rails, like ACH, some additional info like 'sec' code is required

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


This site is for informational purposes only and does not constitute an offer to sell, or the solicitation of an offer to buy, any security. The Goldman Sachs Marquee® platform is for institutional and professional clients only. Some of the services and products described on this site may not be available in certain jurisdictions or to certain types of client. Please contact your Goldman Sachs sales representative with any questions. Nothing on this site constitutes an offer, or an invitation to make an offer from Goldman Sachs to purchase or sell a product. This site is given for purely indicative purposes and does not create any contractual relationship between you and Goldman Sachs. Any market information contained on the site (including but not limited to pricing levels) is based on data available to Goldman Sachs at a given moment and may change from time to time. There is no representation that any transaction can or could have been effected on such terms or at such prices. Please see https://www.goldmansachs.com/disclaimer/sec-div-disclaimers-for-electronic-comms.html for additional information. © 2023 Goldman Sachs. All rights reserved.
Transaction Banking services are offered by Goldman Sachs Bank USA (“GS Bank”). GS Bank is a New York State chartered bank, a member of the Federal Reserve System and a Member FDIC. © 2023 Goldman Sachs. All rights reserved.
Not all products and functionality mentioned on this website are currently available through our API platform.
All loans and deposit products are provided by Goldman Sachs Bank USA, Salt Lake City Branch. Member FDIC.
Brokerage and investment advisory services offered by our investment products are provided by Goldman Sachs & Co. LLC (`‘GS&CO.`’), which is an SEC registered broker-dealer and investment adviser, and member FINRA/SIPC. Research our firm at FINRA's BrokerCheck. Custody and clearing services are provided by Apex Clearing Corporation, a registered broker-dealer and member FINRA/SIPC. Please consider your objectives before investing. A diversified portfolio does not ensure a profit or protect against a loss. Past performance does not guarantee future results. Investment outcomes and projections are forward-looking statements and hypothetical in nature. Neither this website nor any of its contents shall constitute an offer, solicitation, or advice to buy or sell securities in any jurisdictions where GS&Co. is not registered. Any information provided prior to opening an investment account is on the basis that it will not constitute investment advice and that GS&Co. is not a fiduciary to any person by reason of providing such information. For more information about our investment offerings, visit our Full Disclosures.
Investment products are: NOT FDIC INSURED ∙ NOT A DEPOSIT OR OTHER OBLIGATION OF, OR GUARANTEED BY, GOLDMAN SACHS BANK USA ∙ SUBJECT TO INVESTMENT RISKS, INCLUDING POSSIBLE LOSS OF THE PRINCIPAL AMOUNT INVESTED