Get a payment batch
const url = 'https://api.elephants.inc/api/v1/payment-batches/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.elephants.inc/api/v1/payment-batches/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --header 'Authorization: Bearer <token>'Returns a batch with its rows. Visible to the requester and to approvers.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The batch’s ID
Responses
Section titled “Responses”The batch
object
Which side row amounts are entered on
How much the source balance is short of total_deducting, for a viewer who may see balances; null when it covers the batch, the viewer may not see it, or the batch is past approval (its total is on hold)
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Rows whose quote has lapsed; requote the batch when non-zero
Every ready row’s fee lines summed by code in the source currency, with rate and bands null; empty until reviewed, or when a row’s fee is in another currency
object
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The points-cap band split behind a merged booster component: each band’s own rate and the slice of the amount it billed. Null on every other component.
object
The one provider rate the batch was priced at (payout currency per unit of source currency, before fees), when every ready row quotes the same pair and rate; null before review, when the source equals the payout currency, or when rows differ. Fees vary per row by band, so the all-in rate does not.
Rows whose payment is on hold; the batch stays executing while non-zero
The batch’s name
Live rows with a needs_fix issue; pricing and submit wait on zero
The currency every recipient receives
Payout reason code shared by every row
Ele reward points the ready rows earn together; null until reviewed
The batch this one was rerun from
What the batch still holds on the source balance: the total from approval, less each row’s share as it is sent or given back; null before approval and once the batch completes
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The batch whose failed rows this one retries
object
The amount entered for this row, on amount_side; null on a fresh draft row
What differs from the uploaded line: each upload column the row was edited on since the import (the sheet’s text as from, the row’s value as to). Empty for a row as uploaded, a row that did not come from a file, and a removed row.
object
The upload column whose value the row no longer matches
The sheet’s text
The row’s value now; null when cleared
The contact’s name, or the inline recipient’s account holder name
object
object
object
Why the last registration attempt failed, in customer-facing copy. Null once active.
Whether the destination is registered with the payout partner. Only active destinations can be quoted or paid.
object
object
object
Whether the wallet belongs to the sender. An own-account wallet completes the travel rule with no counterparty.
object
object
object
object
The payee’s country (ISO alpha-2).
The payee’s Ele ID as it resolved when the contact was saved, without the @.
Whether the payee is a registered business rather than an individual.
Always true: an Ele ID resolves only to a verified organization.
The payee’s verified business or owner name behind that Ele ID.
Deprecated: read destination instead. Recipient currency and masked account, e.g. “VND ••4471”
Set at review. ready rows carry a quote; every other value names why the row cannot be sent. Null before the first review.
Why the row cannot be or was not paid; null when nothing is wrong. At review, the detail behind the blocker (the issue, or the reason the inline recipient could not be saved). From execution on, a stable code for the client to put words to: recipient_not_registered or execution_blocked, quote_drift, insufficient_funds, cancelled_before_execution, failed_before_execution, already_terminal or execution_refused; and once the batch has sent the payment, payment_failed, payment_reversed or payment_cancelled.
What stops this row from being paid, checked on every read of a draft against the destination field mapping; empty once the row is fine, and always empty after the draft is submitted
object
Stable reason: missing_amount, missing_field, invalid_field, bank_not_found, contact_missing, contact_not_approved, destination_not_ready, no_fiat_destination, currency_mismatch, corridor_unsupported, recipient_required, duplicate_recipient
The recipient input field to fix (e.g. account_number), or amount; null when the issue is about the row as a whole
needs_fix blocks pricing and submit; a warning never does
Plain words for the customer
How the row got here: uploaded from a file, address_book, manual (typed in)
Null while the row pays an inline recipient that is not a contact yet
The payment this row became at submit; pass to getPayment
The row’s payment as it stands, null before submit: awaiting_approval, on_hold (held: the batch waits and resumes it once it can be sent), submitted, processing, succeeded, failed, cancelled, reversed (refunded to the balance).
The row’s accepted quote, priced at review
object
What the batch pays for this row, fees included
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
True once this quote can no longer be executed; approving the batch would fail. Requote the batch to refresh every expired row.
The row’s fee lines, as a single payment’s quote lists them: the partner (network) fee, the Elephants fee and any additive fee
object
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The points-cap band split behind a merged booster component: each band’s own rate and the slice of the amount it billed. Null on every other component.
object
The provider’s rate, payout currency per unit of source currency, before fees (a single quote’s gross_rate)
What the recipient receives
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Every fee line summed; null when the partner fee is in another currency
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The recipient a row pays while it is not a contact yet: the bank fields as given, before submit turns them into a contact and destination
object
What the recipient sees on their statement; the batch’s text when null
Set when the row was taken out of the draft; such rows are never paid
Written once at execution; null until then. sent means the payment was handed to execution: its own status says whether it is submitted, on hold or done. failed carries the refusal in error; cancelled if withdrawn before its turn.
The row as the uploaded file had it: one value per template column, as text
object
The source balance as it stands, for a viewer who may see balances; null otherwise
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The balance the batch is paid from; null until one is chosen
object
Signed URL to GET the file as an attachment, no bearer needed; valid until download_url_expires_at, after which reading the batch again mints a fresh one
Bank statement text shared by every row
draft while rows are edited and priced; awaiting_approval once submitted; executing after approval while rows are sent; completed when every row has a result; cancelled if cancelled or rejected before execution.
Sum of every ready row’s cost; null until reviewed
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Every ready row’s fees summed; null until reviewed, or when a row’s fee is in another currency
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Live rows with a warning
Example
{ "amount_side": "landing", "fee_components": [ { "bands": [ { "band": "within_allowance" } ], "code": "partner_fee" } ], "rows": [ { "amount_side": "landing", "changes": [ { "field": "beneficiary_id" } ], "destination": { "account_type": "individual", "rail": "fiat", "status": "draft" }, "disposition": "ready", "issues": [ { "level": "needs_fix" } ], "origin": "uploaded", "quote": { "fee_components": [ { "bands": [ { "band": "within_allowance" } ], "code": "partner_fee" } ] }, "recipient": { "account_type": "individual" }, "result": "sent" } ], "status": "draft"}Invalid request parameters or body
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Missing, invalid, or expired bearer token
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Too many requests
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
object
Example
{ "error": { "type": "rate_limited" }}Headers
Section titled “Headers”How long to wait before retrying, expressed as delay seconds or an HTTP date
Unexpected server error
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}