Payments
Payment attempts of orders and their outcome. Manual payments waiting for money are confirmed here.
Payments
Objects
Payment
idintegerrequiredID of the record, unique among records of its kind in the store.
order_idintegerrequiredID of the order.
pos_shift_idinteger or nullrequiredID of the register shift (/v1/pos-shifts) that took the money: the Z report assigns the payment to that shift. null — not a register payment.
legal_entity_idinteger or nullrequiredLegal entity that receives the money (/v1/legal-entities), the one of the order; null — the sale is not split between legal entities, and the store default legal entity receives the money.
methodstringrequiredPayment method. manual — a manual method of the store (manual_payment_method_id); balance — the balance of the customer; on_account — on credit, the customer owes the amount; gift_card — a gift card; the other values name the payment provider or the kind of payment.
- Values:
cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_package
manual_payment_method_idinteger or nullrequiredManual payment method of the store (/v1/manual-payment-methods) when method is manual; otherwise null.
statusstringrequiredpending — waiting for money; processing — the provider is processing it; succeeded — paid; failed; partially_refunded; refunded; expired — the payment link expired; voided — cancelled before the money arrived.
- Values:
pendingprocessingsucceededfailedpartially_refundedrefundedexpiredvoided
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
amountintegerrequiredAmount to pay by this payment.
received_amountinteger or nullrequiredAmount actually received; null while the money has not arrived. Received on the order is received_amount minus refunded_amount over its payments.
refunded_amountintegerrequiredRefunded out of the received amount.
tip_amountintegerrequiredTip on top of the order amount.
refunded_tip_amountintegerrequiredRefunded out of the tip.
surcharge_amountintegerrequiredSurcharge for paying in installments, on top of the order amount.
refunded_surcharge_amountintegerrequiredRefunded out of the surcharge.
provider_fee_amountinteger or nullrequiredFee the payment provider deducted from the payment before paying it out to the store. null — the provider does not report charges: cash, a manual method, or a payment that was never charged.
refunded_provider_fee_amountinteger or nullrequiredShare of the fee the provider gave back when the buyer was refunded — as the provider reports it, not pro rata to refunded_amount: a refund outside the provider does not return the fee.
provider_withheld_tax_amountinteger or nullrequiredTax the provider withheld from the payment as a tax agent (Ingresos Brutos at MercadoPago). The withholding with its jurisdiction is in the store tax register.
refunded_provider_withheld_tax_amountinteger or nullrequiredShare of the withheld tax the provider gave back.
tenderobject or nullrequiredPayment in a currency other than the store currency: a USDT invoice, a transfer in dollars, cash in a foreign currency. null — the payment is in the store currency. The payment amounts (amount and the rest) stay in the store currency, and accounting uses them.
Fields · 5
currencystringrequiredCurrency of the payment method: an ISO 4217 code or a crypto asset code such as USDT.
amountstringrequiredInvoice amount in the method currency as a decimal string: it covers amount together with tips and surcharge. Multiplied by the rate it may differ from amount by rounding and by the part of the invoice priced in the method currency directly from the price list.
received_amountstring or nullrequiredReceived in the method currency as a decimal string; null — the received amount is kept only in the store currency (received_amount), or a different coin arrived (received_asset).
tendered_amountstring or nullrequiredCash in a foreign currency: how much was handed over in bills, as a decimal string. Change is given in the store currency. null for other methods.
exchange_rateobject or nullrequiredRate that turned the method amount into the payment amount, snapshotted when the payment was issued; null if there is no rate.
Fields · 6
ratestringrequiredRate as a decimal string: 1 unit of the method currency = rate units of the store currency.
modestring or nullrequiredHow the rate was obtained: auto — the market rate of the source plus the store markup; fixed — the rate set by the store; pegged — the store pegged the method currency to another currency (peg), and the rate is that currency's rate times the peg ratio. null for invoices issued before rate rules existed.
- Values:
autofixedpeggednull
sourcestring or nullrequiredMarket rate source: coingecko — the CoinGecko aggregate price; criptoya_p2p — the median of P2P markets; ar_oficial, ar_blue, ar_mep, ar_ccl, ar_mayorista — dollar rates in Argentina; cbr — the Bank of Russia. null if no source was recorded.
- Values:
coingeckocriptoya_p2par_oficialar_bluear_mepar_cclar_mayoristacbrnull
basestring or nullrequiredMarket rate of the source before the store markup, as a decimal string; null if there is no market base.
markup_bpsinteger or nullrequiredStore markup over the market rate in basis points (100 is 1%); it can be negative. null for a rate set by the store and for invoices issued before rate rules existed.
pegobject or nullrequiredPeg of the method currency to another currency: 1 unit of the method currency = peg.rate units of peg.currency (for example, 1 USDT = 1 USD). Prices set in that currency go into the invoice as they are. null when the rate is not pegged.
Fields · 2
currencystringrequiredCurrency the method currency is pegged to (ISO 4217).
ratestringrequiredPeg ratio as a decimal string: how many units of peg.currency one unit of the method currency is worth.
received_assetobject or nullrequiredCoin that actually arrived when the customer sent something other than what was invoiced and it was valued separately; null — what was invoiced arrived.
Fields · 6
assetstringrequiredCoin code, such as USDC.
amountstringrequiredHow many coins arrived, as a decimal string.
ratestringrequiredCrediting rate as a decimal string: 1 coin = rate units of the store currency.
rate_sourcestring or nullrequiredSource of the crediting rate; manual — the rate was set by hand.
rate_as_ofstring or nullrequiredMoment of the quote or of the manual rate version.
tx_idstring or nullrequiredID of the blockchain or exchange transfer, for reconciliation.
provider_payment_idstring or nullrequiredID of the operation at the payment provider, for reconciliation with its statement; null when there is no provider.
payment_urlstring or nullrequiredPayment page of the provider while the payment waits for money: the link can be sent to the customer. null for a paid or cancelled payment and for a manual method.
confirmablebooleanrequiredThe payment can be confirmed by hand now (POST /v1/payments/{payment}/confirm): it waits for money that a person confirms, not the provider.
replaces_payment_idinteger or nullrequiredThe payment this one replaced when the payment method was corrected; null otherwise.
confirmed_atstring (date-time) or nullrequiredWhen the money was received; null while it has not.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
List order payments changed since a given time
get/payments
Scope: payments:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
order_idintegerOnly records of this order.
- Minimum:
- 1
pos_shift_idintegerOnly records taken by this register shift.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/payments" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"legal_entity_id": 0,
"method": "cash",
"manual_payment_method_id": 0,
"status": "pending",
"currency": "string",
"amount": 0,
"received_amount": 0,
"refunded_amount": 0,
"tip_amount": 0,
"refunded_tip_amount": 0,
"surcharge_amount": 0,
"refunded_surcharge_amount": 0,
"provider_fee_amount": 0,
"refunded_provider_fee_amount": 0,
"provider_withheld_tax_amount": 0,
"refunded_provider_withheld_tax_amount": 0,
"tender": {
"currency": "string",
"amount": "string",
"received_amount": "string",
"tendered_amount": "string",
"exchange_rate": {
"rate": "string",
"mode": "auto",
"source": "coingecko",
"base": "string",
"markup_bps": 0,
"peg": {
"currency": "string",
"rate": "string"
}
}
},
"received_asset": {
"asset": "string",
"amount": "string",
"rate": "string",
"rate_source": "string",
"rate_as_of": "string",
"tx_id": "string"
},
"provider_payment_id": "string",
"payment_url": "string",
"confirmable": true,
"replaces_payment_id": 0,
"confirmed_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Get an order payment
get/payments/{payment}
Scope: payments:read
Parameters
Path
paymentintegerrequiredID of the payment.
Responses
200Success
application/json
Returns Payment
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/payments/{payment}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"legal_entity_id": 0,
"method": "cash",
"manual_payment_method_id": 0,
"status": "pending",
"currency": "string",
"amount": 0,
"received_amount": 0,
"refunded_amount": 0,
"tip_amount": 0,
"refunded_tip_amount": 0,
"surcharge_amount": 0,
"refunded_surcharge_amount": 0,
"provider_fee_amount": 0,
"refunded_provider_fee_amount": 0,
"provider_withheld_tax_amount": 0,
"refunded_provider_withheld_tax_amount": 0,
"tender": {
"currency": "string",
"amount": "string",
"received_amount": "string",
"tendered_amount": "string",
"exchange_rate": {
"rate": "string",
"mode": "auto",
"source": "coingecko",
"base": "string",
"markup_bps": 0,
"peg": {
"currency": "string",
"rate": "string"
}
}
},
"received_asset": {
"asset": "string",
"amount": "string",
"rate": "string",
"rate_source": "string",
"rate_as_of": "string",
"tx_id": "string"
},
"provider_payment_id": "string",
"payment_url": "string",
"confirmable": true,
"replaces_payment_id": 0,
"confirmed_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Confirm that the money of a pending invoice was received
post/payments/{payment}/confirm
Scope: payments:write
Parameters
Path
paymentintegerrequiredID of the payment.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
commentstring or nullComment to the confirmation, kept in the history of the order.
- Max length:
- 500
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Payment
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
payment_not_confirmableThe payment cannot be confirmed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/payments/{payment}/confirm" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"comment": "string"
}{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"legal_entity_id": 0,
"method": "cash",
"manual_payment_method_id": 0,
"status": "pending",
"currency": "string",
"amount": 0,
"received_amount": 0,
"refunded_amount": 0,
"tip_amount": 0,
"refunded_tip_amount": 0,
"surcharge_amount": 0,
"refunded_surcharge_amount": 0,
"provider_fee_amount": 0,
"refunded_provider_fee_amount": 0,
"provider_withheld_tax_amount": 0,
"refunded_provider_withheld_tax_amount": 0,
"tender": {
"currency": "string",
"amount": "string",
"received_amount": "string",
"tendered_amount": "string",
"exchange_rate": {
"rate": "string",
"mode": "auto",
"source": "coingecko",
"base": "string",
"markup_bps": 0,
"peg": {
"currency": "string",
"rate": "string"
}
}
},
"received_asset": {
"asset": "string",
"amount": "string",
"rate": "string",
"rate_source": "string",
"rate_as_of": "string",
"tx_id": "string"
},
"provider_payment_id": "string",
"payment_url": "string",
"confirmable": true,
"replaces_payment_id": 0,
"confirmed_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}