Payments

Payment attempts of orders and their outcome. Manual payments waiting for money are confirmed here.

Loading the search index…

Payments

Objects

Payment

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • order_idintegerrequired

    ID of the order.

  • pos_shift_idinteger or nullrequired

    ID 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 nullrequired

    Legal 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.

  • methodstringrequired

    Payment 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 nullrequired

    Manual payment method of the store (/v1/manual-payment-methods) when method is manual; otherwise null.

  • statusstringrequired

    pending — 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
  • currencystringrequired

    Currency of the amounts, an ISO 4217 code: the currency of the store.

  • amountintegerrequired

    Amount to pay by this payment.

  • received_amountinteger or nullrequired

    Amount actually received; null while the money has not arrived. Received on the order is received_amount minus refunded_amount over its payments.

  • refunded_amountintegerrequired

    Refunded out of the received amount.

  • tip_amountintegerrequired

    Tip on top of the order amount.

  • refunded_tip_amountintegerrequired

    Refunded out of the tip.

  • surcharge_amountintegerrequired

    Surcharge for paying in installments, on top of the order amount.

  • refunded_surcharge_amountintegerrequired

    Refunded out of the surcharge.

  • provider_fee_amountinteger or nullrequired

    Fee 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 nullrequired

    Share 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 nullrequired

    Tax 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 nullrequired

    Share of the withheld tax the provider gave back.

  • tenderobject or nullrequired

    Payment 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
    • currencystringrequired

      Currency of the payment method: an ISO 4217 code or a crypto asset code such as USDT.

    • amountstringrequired

      Invoice 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 nullrequired

      Received 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 nullrequired

      Cash 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 nullrequired

      Rate that turned the method amount into the payment amount, snapshotted when the payment was issued; null if there is no rate.

      Fields · 6
      • ratestringrequired

        Rate as a decimal string: 1 unit of the method currency = rate units of the store currency.

      • modestring or nullrequired

        How 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 nullrequired

        Market 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 nullrequired

        Market rate of the source before the store markup, as a decimal string; null if there is no market base.

      • markup_bpsinteger or nullrequired

        Store 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 nullrequired

        Peg 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
        • currencystringrequired

          Currency the method currency is pegged to (ISO 4217).

        • ratestringrequired

          Peg ratio as a decimal string: how many units of peg.currency one unit of the method currency is worth.

  • received_assetobject or nullrequired

    Coin 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
    • assetstringrequired

      Coin code, such as USDC.

    • amountstringrequired

      How many coins arrived, as a decimal string.

    • ratestringrequired

      Crediting rate as a decimal string: 1 coin = rate units of the store currency.

    • rate_sourcestring or nullrequired

      Source of the crediting rate; manual — the rate was set by hand.

    • rate_as_ofstring or nullrequired

      Moment of the quote or of the manual rate version.

    • tx_idstring or nullrequired

      ID of the blockchain or exchange transfer, for reconciliation.

  • provider_payment_idstring or nullrequired

    ID of the operation at the payment provider, for reconciliation with its statement; null when there is no provider.

  • payment_urlstring or nullrequired

    Payment 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.

  • confirmablebooleanrequired

    The 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 nullrequired

    The payment this one replaced when the payment method was corrected; null otherwise.

  • confirmed_atstring (date-time) or nullrequired

    When the money was received; null while it has not.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

Endpoints

List order payments changed since a given time

get/payments

Scope: payments:read

Parameters

Query

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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_idinteger

    Only records of this order.

    Minimum:
    1
  • pos_shift_idinteger

    Only records taken by this register shift.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of Paymentrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/payments" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • paymentintegerrequired

    ID of the payment.

Responses

200Success

application/json

Returns Payment

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/payments/{payment}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • paymentintegerrequired

    ID of the payment.

Header

  • Idempotency-Keystring

    Unique 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 null

    Comment to the confirmation, kept in the history of the order.

    Max length:
    500

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — body.json
{
  "comment": "string"
}
Example response · 200
{
  "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"
}