/transactions/{userId}/payments/previewPayment Preview for ACH and Wire
Previews a payment before execution. Returns fee breakdown and transaction details without actually processing the payment. Supports ACH, Wire, International Wire, and FV Net payment types.
Path variables
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
userId | string | Required | — | Unique user ID initiating the payment. |
Headers
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
session-token | string | Required | — | SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header. |
Request body
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
TransferType | string | Required | ACH | WIRE | Type of payment to preview. |
CounterpartyId | string | Required | — | Counterparty ID for the payment. |
InstrumentId | string | Required | — | Payment instrument ID. |
IsCryptoTransaction | string | Required | true | false | Whether this is a crypto transaction. |
PaymentPurpose | string | Required | Refer to the Payment Purpose endpoint to get the list of possible values. | Purpose code for the payment. |
Amount | string | Required | — | Payment amount. |
SupportingDocument | string | Optional | — | File ID of a previously uploaded document (see **File Upload** endpoint). Required when the Amount exceeds the configured threshold for the user's group. The threshold value can be retrieved from the Config Data endpoint. |
Description | string | Optional | — | Payment description. |
Example request
{
"TransferType": "ACH",
"CounterpartyId": "{{counterpartyId}}",
"InstrumentId": "{{instrumentId}}",
"IsCryptoTransaction": "false",
"PaymentPurpose": "Asset_Purchase",
"Amount": "100.00",
"SupportingDocument": "-870429145188356199",
"Description": "Test API"
}To attach a supporting document, add `SupportingDocument` using the file ID returned by the **File Upload** endpoint and update the `CounterpartyId` and `InstrumentId` with the actual counterparty and instrument IDs.
Response
| Field | Type | Possible values | Description |
|---|---|---|---|
ResponseCode | integer | 200 | 201 | 204 | 301 | 400 | 401 | 403 | 404 | 410 | 422 | 500 | 503 | API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized). |
ResponseMessage | string | Success | Created | NoContent | BadRequest | Unauthorized | Forbidden | NotFound | Gone | UnprocessableContent | ServerError | ResourceMoved | ServiceUnAvailable | UnProcessableEntity | Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome. |
ResponseData | object | Please refer to below example for response body | Payment preview details including fees and routing information. |
Example response
{
"ResponseCode": 200,
"ResponseMessage": "Success",
"ResponseData": {
"Currency": "USD",
"TransferType": {
"Name": "Payment - Domestic (ACH)"
},
"MainAmount": "100.00",
"Fees": 0,
"TotalAmount": "100.00",
"FromAccount": {
"Id": "-2050372247559426224",
"Number": "****2890",
"Type": "Account (USD)"
},
"Receiver": {
"Id": "4155588038957117405",
"Name": "Acme Corporation private ltd",
"Email": "accounting@example.com"
},
"ReceiverPaymentInstrument": {
"Id": "4398782418835124189",
"RoutingNumber": "021000021",
"AccountNumber": "****9012"
},
"PaymentPurpose": "Asset_Purchase",
"Description": "Test API",
"TransactionCryptoBuySellActivity": "No",
"Transfer_Originator_Type": "INDIVIDUAL|Individual",
"Beneficiary_Bank_City": "New York",
"Beneficiary_Bank_Address": "270 Park Avenue",
"Payment_Instrument_ID": "4398782418835124189|Counterparty Instrument Record (4398782418835124189)",
"Beneficiary_Address": "Building A, Suite 200 500 Technology Drive",
"Transfer_Originator": "John Doe",
"Beneficiary_ID": "4155588038957117405|Counterparty (4155588038957117405)",
"Beneficiary_City": "San Jose",
"Beneficiary_Email": "accounting@example.com",
"Deposit_Gateway": "manual_processing",
"Beneficiary_Bank_Name": "Chase Bank",
"Beneficiary_Bank_Postal_Code": "10017",
"Beneficiary_Company_Name": "Acme Corporation private ltd",
"Beneficiary_Bank_Country": "US",
"Beneficiary_Postal_Code": "95134",
"US_Routing_Number": "021000021",
"Beneficiary_Bank_State": "NY",
"US_Account_Number": "****9012",
"Beneficiary_Country": "US|United States of America",
"Bank_Account_Type": "Checking"
}
}This endpoint previews the payment without executing it. Use Perform Payment to execute.
Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.