API docs by Redocly

OlaPagos API (1.0.6)

Download OpenAPI specification:

API for managing payments.

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a payment fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single payment is created.

To perform an idempotent request, provide an Idempotence-Key header with a unique value (e.g., a UUID) in your request. The server stores the result of the first request with a given key and returns the same response for subsequent requests with that same key.

Sandbox mode

When a merchant is in sandbox mode, special logic applies:

  • The server adds sandbox: true to the payment metadata.
  • A Pay In with metadata.confirm: true will be automatically confirmed. Pay Ins using payer DNI 11111111 continue to be automatically confirmed for backwards compatibility.
  • If a Pay Out is created with a payee CBU of 1111111111111111111111, the payment will be automatically confirmed.
  • Sandbox payments do not increase the merchant's balance.

Changelog

v1.0.6 - 2026-09-04

  • Added: Pay Ins accept an optional merchant reference and return it in payment responses and callbacks.

v1.0.5 - 2026-08-23

  • Added: RUB bank-transfer Pay Ins now accept payer.bankID to identify the payer's bank.
  • Changed: Sandbox Pay Ins can be automatically confirmed by setting metadata.confirm to true.

v1.0.4 - 2026-07-08

  • Added: Pay In paymentMethod now supports mercado_pago_qr.

v1.0.3 - 2026-05-26

  • Added: Pay In paymentMethod now supports mercado_pago_checkout; payer is only required for bank_transfer.

v1.0.2 - 2026-05-16

  • Added: Pay In responses and callbacks now include nullable payer.cbu.

v1.0.1 - 2026-05-11

  • Changed: Pay Out payee fields documentNumber and documentType are now optional.

v1.0.0

  • Initial release.

Merchant

Get Merchant Balance

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payments

Create a Pay In

Authorizations:
apiKeyAuth
header Parameters
Idempotence-Key
required
string <= 254 characters
Example: some-unique-key

A unique string used to ensure that requests are processed only once.

Request Body schema: application/json
required
One of
amount
required
string

Amount as a string to avoid precision issues.

currency
required
string
Value: "ARS"
paymentMethod
required
string
Value: "bank_transfer"
required
object (ARSPayerDto)

Payer details for an ARS bank-transfer Pay In.

returnUrl
string <uri>
merchantReference
string <= 255 characters

Merchant-defined reference for correlating this payment with the merchant's own records.

object <= 20 properties

Max key length = 40, Max value length = 500, Max metadata size <= 4 kB, Types: string, number, boolean, Flat object only

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "amount": "1000",
  • "currency": "ARS",
  • "paymentMethod": "bank_transfer",
  • "payer": {
    },
  • "returnUrl": "http://example.com",
  • "merchantReference": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
Example
{
  • "payment_url": "https://payment.site.com/pay/some-unique-key",
  • "payment": {
    },
  • "instructions": {
    }
}

Callback payload samples

Callback
POST: Pay-in Callback
Content type
application/json
{
  • "id": "string",
  • "status": "succeeded",
  • "currency": "ARS",
  • "input_amount": "string",
  • "fact_amount": "string",
  • "payer": {
    },
  • "merchant_reference": "string",
  • "metadata": {
    }
}

Get a Pay In

Authorizations:
apiKeyAuth
path Parameters
publicId
required
string

Public ID of the payment

Responses

Response samples

Content type
application/json
{
  • "payment_url": "http://example.com",
  • "payment": {
    },
  • "instructions": {
    }
}

Create a Pay Out

Authorizations:
apiKeyAuth
header Parameters
Idempotence-Key
required
string <= 254 characters
Example: some-unique-key

A unique string used to ensure that requests are processed only once.

Request Body schema: application/json
required
amount
required
string

Minimum amount is 20000, maximum is 5000000. Amount as a string to avoid precision issues.

currency
required
string = 3 characters
paymentMethod
required
string (PaymentMethod)
Value: "bank_transfer"
required
object (PayeeDto)
returnUrl
string <uri>
object <= 20 properties

Max key length = 40, Max value length = 500, Max metadata size <= 4 kB, Types: string, number, boolean, Flat object only

Responses

Callbacks

Request samples

Content type
application/json
{
  • "amount": "1000",
  • "currency": "ARS",
  • "paymentMethod": "bank_transfer",
  • "payee": {
    },
  • "returnUrl": "http://example.com",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "payment_url": "https://payment.site.com/payout/some-unique-key",
  • "payment": {
    },
  • "payee": {
    }
}

Callback payload samples

Callback
POST: Payout Callback
Content type
application/json
{
  • "id": "string",
  • "status": "succeeded",
  • "currency": "ARS",
  • "input_amount": "string",
  • "fact_amount": "string",
  • "metadata": {
    }
}

Get a Pay Out

Authorizations:
apiKeyAuth
path Parameters
publicId
required
string

Public ID of the payment

Responses

Response samples

Content type
application/json
{
  • "payment_url": "http://example.com",
  • "payment": {
    },
  • "payee": {
    }
}