Integration via API - Step 4: Payout Status
Payment Status
Goldman Sachs Transaction Banking (TxB) provides a robust, near real-time framework for monitoring the lifecycle of every transaction. Every transaction processed by TxB transitions through a standardized set of statuses, this uniformity ensures that Widget Co’s systems can handle diverse payment types using a single logic flow.
| Status | Type | Description |
|---|---|---|
| PENDING | Intermediate | Payment processing has been delayed, e.g., because of insufficient funds or currency cut-off. |
| ACCEPTED | Intermediate | Payment processing within TxB is complete and we are waiting to send to network. |
| RELEASED | Terminal / Intermediate | Payment network has confirmed receipt of the payment. In some cases, this is a terminal step. |
| SETTLED | Terminal | Payment receiver has confirmed receipt. |
| RETURNED | Terminal | The payment network or receiver has canceled the payment and returned it to TxB. |
| REJECTED | Terminal | TxB stopped the payment from being processed due to an error, e.g., incorrect account number, currency rule validation failure. |
| RECEIVED | Incoming Credits | You have received an incoming payment that has been posted to your TxB account. |
See payment state diagram in this link. See payment status description in this link.
Widget Co. can maintain full payment status visibility through two primary mechanisms: an event-driven PUSH model (Webhooks) and an on-demand PULL model (API Query).
PUSH Model: Webhooks
Webhooks can be the driving mechanism for high-efficiency operations. Widget Co. uses TxB Webhooks to get immediate updates on payment status changes for both incoming and outgoing transactions, eliminating the need for polling TxB Ledger APIs, streamlining operations and enabling Widget Co.’s internal ledgers to be updated in near real-time. TxB "pushes" data to Widget Co via Webhooks only when a payment status changes or a new transaction is credited, ensuring timely and accurate alerts:
- Payouts: Updates are sent as payments move through statuses like ACCEPTED, RELEASED, and SETTLED.
- Incoming Transactions: Notifications are triggered by new credits or returned payouts, with statuses such as RECEIVED.
The JSON payload delivered via Webhooks contains critical metadata to ensure accurate processing:
| Field | Description |
|---|---|
| eventId | A UUID for the specific event to prevent duplicate processing (idempotency). |
| paymentEndToEndId | The unique identifier provided by Widget Co. during initiation. |
| status | Payment status. |
| statusTime | The time that the status changed. Note: Always use this field to determine the "latest" state if webhooks arrive out of order. |
| paymentExecutedValueDate | The date that funds are transferred. |
| eventName | The specific event type (e.g., PAYMENT_STATUS.SETTLED). |
| eventTimestamp | The time the webhook was generated by the TxB system. |
Sample Webhook Payload
{
"deliveryId": "82e90be1-a5ef-4cbd-a0fb-d1395d9b18b1",
"events": {
"eventId": "a53b8074-f78b-4c4c-b96e-0ec40c91127f",
"eventData": {
"cases": {
"links": [],
"hasLinkedCases": false
},
"amount": 4012,
"fxInfo": {
"paymentAmount": 4012,
"paymentCurrency": "USD"
},
"returns": {
"links": [],
"hasReturnDetails": false
},
"amountType": "PAYMENT",
"identifiers": {
"gsPostingIds": [
"GI2602700165872"
],
"railReferenceId": {
"rail": "FEDWIRE",
"railId": "20260127MMQFMCU7000402"
},
"paymentRequestId": " PaymentReqID0000002",
"gsUniquePaymentId": " GI2602700165872",
"paymentEndToEndId": "TxE2EID000021"
},
"cancelations": {
"links": [],
"hasCancelationDetails": false
},
"paymentStatus": {
"status": "SETTLED",
"statusTime": "2026-01-27T15:06:51.72Z"
},
"paymentCurrency": "USD",
"paymentExecutedValueDate": "2026-01-27"
},
"eventName": "PAYMENT_STATUS.SETTLED",
"eventTimestamp": "2026-01-27T15:06:51.72Z"
}
} To improve the reliability of payment updates, TxB offers an automated retry logic for webhooks that fail to receive a successful acknowledgment from Widget Co’s server. More details about the retry logic can be found here.
TxB utilizes an exponential back-off schedule, this approach spaces out subsequent attempts to avoid overwhelming Widget Co.’s infrastructure. Once Widget Co. has received the statuses via Webhooks, they must update their internal database with that status for the corresponding payment for further reference.
PULL Model: API Query
In addition to utilising Webhooks, Widget Co. seeks to enable its back-office operations team to query individual payment statuses to manage exceptions effectively. Given that payment status information is maintained within the company’s data lake, the primary method should be to query this internal repository.
If the required information is unavailable or an exception is open, Widget Co. may confirm that payment statuses are aligned by accessing the TxB data platform. Widget Co. utilizes the TxB Query Payment Status API (PULL model), which provides TxB’s payment status for the transaction. This API enables separate verification of transaction statuses apart from event-driven webhook notifications.
While Webhooks facilitate near real-time automation, the Query API supports operational resilience and exception handling:
- Reconciliation: Synchronization of internal records with the TxB data platform (e.g., ensure no events were missed during network outages).
- Exception Handling: Investigating payments that remain in an intermediate state (e.g., PENDING) longer than expected.
- Manual Audits: Providing back-office staff with a real-time view of a payment's journey, including detailed reason codes for failures.
- Fallback Mechanism: Retrieving the latest status if a webhook delivery fails after all automated retries have been exhausted.
Request POST https://api.test.txb.gs.com/v2/payments/query
// The APi request body is an array, and thus it is possible to query multiple payments in a single request.
[
{
// idType = PAYMENTENDTOENDID facilitates querying and tracking status
// of individual payment by the payment's end to end Id.
"idType": "PAYMENTENDTOENDID",
"idValue": "ClientUniqueE2EId"
},
{
// idType = PAYMENTREQUESTID facilitates querying by the payment request Id
// and helps to track the payment status when multiple payments are sent using single payment request.
"idType": "PAYMENTREQUESTID",
"idValue": "ClientUniquePaymentRequest"
}
]Response
[
{
"identifiers": {
"paymentRequestId": "ClientUniquePaymentRequest",
"paymentEndToEndId": "ClientUniqueE2EId",
"gsUniquePaymentId": " GI2602700165872",
"railReferenceId": {
"rail": "FEDWIRE",
"railId": "20260127MMQFMCU7000402"
}
},
"paymentStatus": {
"status": "SETTLED",
"statusTime": "2026-01-27T15:06:51.72Z"
},
"paymentExecutedValueDate": "2026-01-27",
"amount": 100,
"paymentCurrency": "USD",
"fxInfo": {
"paymentAmount": 100.00,
"paymentCurrency": "USD",
"sourceCurrency": "USD"
},
"returns": {
"hasReturnDetails": false
},
"cancelations": {
"hasCancelationDetails": false
}
}
]
//null values have been removed for easier reading Congratulations, you have successfully completed the entire payment lifecycle. The subsequent step involves monitoring your bank accounts in near real-time.
Additional Information
- Payment Life-Cycle
- Query payment status
- Webhook Spec
- Webhook Intro
- Webhook Retry Policy
- Webhook Auth process
TxB offers enhanced Webhook authentication features to ensure that incoming webhooks are appropriately authenticated and have not been tampered with during transit. TxB supports two primary methods for authenticating webhooks, which can be used independently or in tandem: Mutual TLS (mTLS) and Signature Verification
| 1: Connect | 2: Create Account | 3: Payout | 4: Payout Status | 5: Account Status | 6: Reconcile |
|---|
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.