Payment Checkout & Payment Links API

Welcome to the official developer documentation for Olanzo Payment Checkout (https://checkout-dev.jirafix.net). Use this HTTP API to create hosted checkout sessions, generate 1:1 direct payment links, auto-match customer profiles, and receive real-time webhook confirmations for SINPE Móvil payments.

Environment

You are viewing the documentation for the host that served this page. The Target Host badge and every code sample use this same environment automatically.

Credentials (sk_live_ / sk_test_) are issued per merchant per environment. A Dev key never works on Production. Open /docs on another host to see that environment.

1. Authentication

Authenticate server-to-server requests with your business's E-commerce secret key. In the Olanzo Portal: Create → Merchant → your business → E-commerce → API Keys → Secret Key → Copy. The same key works for payment links and checkout sessions.

Authorization: Bearer sk_test_YOUR_SECRET_KEY

Calling from a browser or mobile app

Have your frontend call your own backend, and let your backend call Olanzo with the secret key:

// Browser — no Olanzo key is exposed here.
const response = await fetch("/api/create-payment-link", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ invoice_id: "INV-2026-001" })
});

const paymentLink = await response.json();
window.location.href = paymentLink.url;   // send the customer to the hosted page

Your backend then performs the request shown in the Node.js tabs below, using the secret key it holds.

Key types

Identifier formats

Identifiers are opaque — match on the prefix, never on a fixed length or a digit pattern.

2. External Customer Auto-Matching & Creation

When creating a checkout session or payment link, you can provide customer contact information in the customer object. Olanzo evaluates customer identity before creation:

3. Create Checkout Session

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Idempotency-Key: ORD-12345-RETRY-01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "CRC",
    "order_reference": "ORD-12345",
    "description": "Shopping cart order",
    "success_url": "https://your-store.example/thanks?session={SESSION_ID}",
    "failure_url": "https://your-store.example/failed",
    "cancel_url": "https://your-store.example/cart",
    "customer": {
      "id": "cust_9981",
      "first_name": "María",
      "last_name": "López",
      "email": "maria.lopez@example.com",
      "phone": "80000000",
      "country_code": 506,
      "cedula": "100000000",
      "id_type": "fisica"
    }
  }'

const response = await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_YOUR_SECRET_KEY",
    "Idempotency-Key": "ORD-12345-RETRY-01",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 25000,
    currency: "CRC",
    order_reference: "ORD-12345",
    description: "Shopping cart order",
    success_url: "https://your-store.example/thanks?session={SESSION_ID}",
    failure_url: "https://your-store.example/failed",
    cancel_url: "https://your-store.example/cart",
    customer: {
      id: "cust_9981",
      first_name: "María",
      last_name: "López",
      email: "maria.lopez@example.com",
      phone: "80000000",
      country_code: 506,
      cedula: "100000000",
      id_type: "fisica"
    }
  })
});
const session = await response.json();
// Return session.checkout_url to your frontend and redirect the customer there.
return session.checkout_url;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "sk_test_YOUR_SECRET_KEY");
client.DefaultRequestHeaders.Add("Idempotency-Key", "ORD-12345-RETRY-01");

var body = new {
    amount          = 25000m,
    currency        = "CRC",
    order_reference = "ORD-12345",
    description     = "Shopping cart order",
    success_url     = "https://your-store.example/thanks?session={SESSION_ID}",
    failure_url     = "https://your-store.example/failed",
    cancel_url      = "https://your-store.example/cart",
    customer = new {
        id           = "cust_9981",
        first_name   = "María",
        last_name    = "López",
        email        = "maria.lopez@example.com",
        phone        = "80000000",
        country_code = 506,
        cedula       = "100000000",
        id_type      = "fisica"
    }
};

var json    = JsonSerializer.Serialize(body, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower });
var content = new StringContent(json, Encoding.UTF8, "application/json");
var resp    = await client.PostAsync("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions", content);
var result  = await resp.Content.ReadFromJsonAsync<JsonElement>();
var checkoutUrl = result.GetProperty("checkout_url").GetString();
// Redirect user → checkoutUrl

import requests

payload = {
    "amount":          25000,
    "currency":        "CRC",
    "order_reference": "ORD-12345",
    "description":     "Shopping cart order",
    "success_url":     "https://your-store.example/thanks?session={SESSION_ID}",
    "failure_url":     "https://your-store.example/failed",
    "cancel_url":      "https://your-store.example/cart",
    "customer": {
        "id":           "cust_9981",
        "first_name":   "María",
        "last_name":    "López",
        "email":        "maria.lopez@example.com",
        "phone":        "80000000",
        "country_code": 506,
        "cedula":       "100000000",
        "id_type":      "fisica"
    }
}

resp = requests.post(
    "http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions",
    json=payload,
    headers={
        "Authorization":   "Bearer sk_test_YOUR_SECRET_KEY",
        "Idempotency-Key": "ORD-12345-RETRY-01"
    }
)
session = resp.json()
checkout_url = session["checkout_url"]
# Redirect your user to checkout_url

{
  "session_id": "9b1deb4d-3b7d-4169-9c47-c0e60807b5a1",
  "session_code": "cs_9b1deb4d3b7d41699c47c0e60807b5a1",
  "checkout_url": "https://checkout-dev.jirafix.net/checkout/cs_9b1deb4d3b7d41699c47c0e60807b5a1?lang=es",
  "expires_at": "2026-08-06T20:00:00Z",
  "status": "pending",
  "order_id": "PO-AB23CD45"
}

4. Get Session Details

curl "http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1"

const resp = await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1");
const session = await resp.json();

using var client = new HttpClient();
var resp = await client.GetAsync("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1");
var json = await resp.Content.ReadAsStringAsync();

import requests
resp = requests.get("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1")
print(resp.json())

5. Poll Session Status

curl "http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/status"

const resp = await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/status");
const { status } = await resp.json();

using var client = new HttpClient();
var resp = await client.GetAsync("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/status");

import requests
resp = requests.get("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/status")
print(resp.json()["status"])

{
  "session_code": "cs_9b1deb4d3b7d41699c47c0e60807b5a1",
  "status": "pending"
}

6. Cancel Session

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/cancel"

await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/cancel", { method: "POST" });

using var client = new HttpClient();
await client.PostAsync("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/cancel", null);

import requests
requests.post("http://checkoutapi-dev.jirafix.net/v1/payments/checkout/sessions/cs_9b1deb4d3b7d41699c47c0e60807b5a1/cancel")

7. Create Payment Link

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "INV-2025-001",
    "additional_reference": "PO-88234",
    "amount_net": 25000,
    "iva_rate": 13,
    "description": "Monthly subscription — August 2026",
    "expires_at": "2026-11-01T20:40:00Z",
    "customer": {
      "first_name": "María",
      "last_name": "López",
      "email": "maria.lopez@example.com",
      "phone": "80000000",
      "country_code": 506,
      "cedula": "100000000",
      "id_type": "fisica"
    }
  }'

const response = await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_YOUR_SECRET_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    reference: "INV-2025-001",
    additional_reference: "PO-88234",
    amount_net: 25000,
    iva_rate: 13,
    description: "Monthly subscription — August 2026",
    expires_at: "2026-11-01T20:40:00Z",
    customer: {
      first_name: "María",
      last_name: "López",
      email: "maria.lopez@example.com",
      phone: "80000000",
      country_code: 506,
      cedula: "100000000",
      id_type: "fisica"
    }
  })
});
const link = await response.json();
console.log(link.url); // https://checkout-dev.jirafix.net/pay/plk_a1b2c3d4e5f60718

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "sk_test_YOUR_SECRET_KEY");

var body = new {
    reference            = "INV-2025-001",
    additional_reference = "PO-88234",
    amount_net           = 25000m,
    iva_rate             = 13m,
    description          = "Monthly subscription — August 2026",
    expires_at           = "2026-11-01T20:40:00Z",
    customer = new {
        first_name   = "María",
        last_name    = "López",
        email        = "maria.lopez@example.com",
        phone        = "80000000",
        country_code = 506,
        cedula       = "100000000",
        id_type      = "fisica"
    }
};

var json    = JsonSerializer.Serialize(body, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower });
var content = new StringContent(json, Encoding.UTF8, "application/json");
var resp    = await client.PostAsync("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links", content);
var result  = await resp.Content.ReadAsStringAsync();

import requests

payload = {
    "reference":            "INV-2025-001",
    "additional_reference": "PO-88234",
    "amount_net":           25000,
    "iva_rate":             13,
    "description":          "Monthly subscription — August 2026",
    "expires_at":           "2026-11-01T20:40:00Z",
    "customer": {
        "first_name":   "María",
        "last_name":    "López",
        "email":        "maria.lopez@example.com",
        "phone":        "80000000",
        "country_code": 506,
        "cedula":       "100000000",
        "id_type":      "fisica"
    }
}

resp = requests.post(
    "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links",
    json=payload,
    headers={"Authorization": "Bearer sk_test_YOUR_SECRET_KEY"}
)
print(resp.json()["url"])

{
  "link_id": "7c1f5e02-9d3a-4b77-9a41-2f0c8e6b1d55",
  "link_code": "plk_a1b2c3d4e5f60718",
  "url": "https://checkout-dev.jirafix.net/pay/plk_a1b2c3d4e5f60718?lang=es",
  "reference": "INV-2025-001",
  "order_id": "PL-AB23CD45",
  "additional_reference": "PO-88234",
  "description": "Monthly subscription — August 2026",
  "statement_description": null,
  "amount_net": 25000,
  "iva_rate": 13,
  "iva_amount": 3250,
  "amount_total": 28250,
  "currency": "CRC",
  "status": "unpaid",
  "is_test_mode": true,
  "reusable": false,
  "max_payments": null,
  "allowed_payment_methods": ["sinpe_mobile"],
  "locale": "es-CR",
  "success_url": null,
  "failure_url": null,
  "cancel_url": null,
  "webhook_url": null,
  "notify": { "events": null },
  "customer": {
    "id": "cust_9981",
    "type": "individual",
    "first_name": "María",
    "last_name": "López",
    "business_name": null,
    "email": "maria.lopez@example.com",
    "phone": "80000000",
    "country_code": 506,
    "cedula": "100000000",
    "id_type": "fisica"
  },
  "metadata": { "invoice_id": "inv_8492", "source": "erp" },
  "expires_at": "2026-08-12T20:40:00Z",
  "created_at": "2026-08-05T15:10:00Z",
  "paid_at": null,
  "sinpe_ref": null,
  "transaction_id": null,
  "cancelled_at": null
}

8. Amounts & IVA

Money is the easiest thing to get wrong, so these rules are exact.

Worked example — ₡25 000 net at 13%:

iva_amount   = round(25000 × 13 ÷ 100) = round(3250.00) = 3250
amount_total = 25000 + 3250              = 28250

Mixed rates via line_items:

"line_items": [
  { "name": "Consulting hours", "quantity": 10, "unit_price": 2000, "iva_rate": 13 },
  { "name": "Medical supplies", "quantity": 1,  "unit_price": 5000, "iva_rate": 0  }
]

// line 1: net 20000, iva round(20000 × 13 ÷ 100) = 2600
// line 2: net  5000, iva 0
// amount_net 25000, iva_amount 2600, amount_total 27600

A discount, sent as a positive price on a discount line:

"line_items": [
  { "name": "Consulting hours", "quantity": 10, "unit_price": 2000, "iva_rate": 13 },
  { "name": "Launch promotion",  "quantity": 1, "unit_price": 3000, "iva_rate": 13,
    "line_type": "discount" }
]

// line 1: net 20000, iva round(20000 × 13 ÷ 100) = 2600   ADDED
// line 2: net  3000, iva round( 3000 × 13 ÷ 100) =  390   SUBTRACTED
// amount_net 17000, iva_amount 2210, amount_total 19210

9. Get a Payment Link

curl "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

const resp = await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718", {
  headers: { "Authorization": "Bearer sk_test_YOUR_SECRET_KEY" }
});
const link = await resp.json();
if (link.status === "paid") {
  // Settle the order. paid_at / sinpe_ref identify the bank credit.
}

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "sk_test_YOUR_SECRET_KEY");
var resp = await client.GetAsync("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718");

import requests
resp = requests.get(
    "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718",
    headers={"Authorization": "Bearer sk_test_YOUR_SECRET_KEY"}
)
print(resp.json()["status"])

10. List Payment Links

curl "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links?reference=INV-2025-001" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

const url = "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links?status=unpaid&page_size=50";
const resp = await fetch(url, {
  headers: { "Authorization": "Bearer sk_test_YOUR_SECRET_KEY" }
});
const { data, total_count } = await resp.json();

{
  "data": [ { "link_id": "…", "link_code": "plk_a1b2c3d4e5f60718", "status": "unpaid", "…": "…" } ],
  "total_count": 1,
  "page": 1,
  "page_size": 25,
  "request_id": "req_71d11cfe"
}

11. Update a Payment Link

curl -X PATCH "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Monthly subscription — September 2026",
    "expires_at": "2026-11-01T20:40:00Z"
  }'

12. Cancel a Payment Link

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/cancel" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

13. List a Link's Payment Attempts

curl "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/payments" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

const resp = await fetch(
  "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/payments",
  { headers: { "Authorization": "Bearer sk_test_YOUR_SECRET_KEY" } }
);
const { data } = await resp.json();
// Exactly one attempt can be "confirmed"; the rest are abandoned or expired sessions.
const settled = data.find(a => a.status === "confirmed");

{
  "link_code": "plk_a1b2c3d4e5f60718",
  "data": [
    {
      "session_code": "cs_9b1deb4d3b7d41699c47c0e60807b5a1",
      "status": "confirmed",
      "amount": 28250,
      "currency": "CRC",
      "created_at": "2026-08-05T19:58:00Z",
      "confirmed_at": "2026-08-05T20:10:00Z",
      "expires_at": "2026-08-05T20:28:00Z"
    }
  ],
  "request_id": "req_71d11cfe"
}

14. Resolve Payment Link → Session

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/session"

const resp = await fetch("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/session", {
  method: "POST"
});
const { session_code, checkout_url } = await resp.json();

using var client = new HttpClient();
var resp = await client.PostAsync("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/session", null);
var json = await resp.Content.ReadAsStringAsync();

import requests
resp = requests.post("http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/session")
print(resp.json())

Confirming before paying

These two flags make the customer answer something before a payment page will open. They do different jobs, and it is worth being precise about which:

While the gate is unpassed, resolving the link returns state confirmation_required and no session is minted. The response also withholds the order number itself — otherwise the page would display the very answer the customer is being asked for. For the same reason, while require_order_confirmation is unpassed the description is withheld too whenever it happens to contain the order number; a description that does not is returned unchanged.

The resolve response's require_order_confirmation and require_cedula are the effective gate — what this link will actually ask this customer. Render your confirm step from those two, not from the flags on a link read: a link created with require_cedula and a customer.cedula resolves with require_cedula: false, and a cedula posted to /confirm for such a link is ignored rather than rejected.

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/confirm" \
  -H "Content-Type: application/json" \
  -d '{"order_number":"INV-2026-0142","cedula":"1-1234-5678"}'

Sending the link

A payment link does not email or text the customer unless you ask. Add an optional send block on create, or call the send endpoint later. The destination is always the customer on this link — we never look up another address from CRM or the bank.

Create never waits on the outbound send. The first attempt is queued as pending and a background sweep delivers it. Reminders sit on the same ledger until their time. Create and get echo a sends array once anything was queued; list omits it when empty.

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/payment-links/plk_a1b2c3d4e5f60718/send" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channels":["email","sms"],"reminders":[{"days_before_expiry":3}]}'

15. How a SINPE payment reaches a link

This is the part that differs most from a card gateway, so it is worth reading before you write any code.

16. Link Lifecycle & Status

Status values

There is no separate processing or failed status. A payment in flight is still unpaid — check GET …/payments to see whether an attempt is open. A failed or abandoned attempt simply leaves the link unpaid so the customer can try again; it never marks the link itself as failed.

Rules the lifecycle guarantees

Paying in instalments

Set allow_partial_payment: true and the customer can settle the link over several payments. On each visit they choose an amount, we open a checkout for exactly that figure, and the link stays payable until the balance reaches zero.

Knowing whether the customer saw it

opened_at is stamped the first time the payment page is opened, and open_count counts every visit. An unpaid link with opened_at: null was never seen — chase the delivery, not the payment.

Collecting your own details

custom_fields adds your own questions to the payment page. The customer answers them before paying, and the answers come back on the link and in the payment webhook — so you can ask for a table number, a delivery note or an internal reference without building your own form.

"custom_fields": [
  { "key": "table_number", "label": "Table number", "type": "numeric", "required": true },
  { "key": "allergies",    "label": "Allergies",    "type": "text",    "max_length": 120 },
  { "key": "collection",   "label": "Collection",   "type": "dropdown", "options": ["Pick up", "Deliver"] }
]

Choosing which events you receive

By default a link pushes every payment_link.* event. Use notify.events to narrow that to the ones you act on:

"notify": { "events": ["payment_link.paid", "payment_link.expired"] }

17. Errors

Every payment-link error uses one shape. error is human-readable, error_code is what you branch on, and request_id is what you quote to support — it is also returned as the X-Correlation-Id response header on every response, success included.

{
  "error": "customer.country_code is required when customer.phone is set.",
  "error_code": "invalid_field",
  "field": "customer.country_code",
  "request_id": "req_71d11cfe"
}

18. Outbound Webhooks

When a payment is matched and confirmed, Olanzo sends a POST to your webhook URL — the link's own webhook_url if set, otherwise the one configured for your business under Create → Merchant → your business → E-commerce → Customer return URLs.

Your webhook URL must use https://. These notifications carry payment details and the signature you verify them with, so we do not send them over an unencrypted connection. A plain http:// address is refused when you set or change it — on a business, a payment link, or an individual checkout session. Addresses that resolve to private, internal or loopback ranges are refused for the same reason.

If you configured an http:// address before this requirement, it keeps working and nothing stops today — but move it to https://, because any later edit to that field will be refused until you do.

{
  "event": "payment.confirmed",
  "session_id": "cs_9b1deb4d3b7d41699c47c0e60807b5a1",
  "amount": 28250,
  "currency": "CRC",
  "order_reference": "INV-2025-001",
  "metadata": { "invoice_id": "inv_8492", "source": "erp" },
  "customer": {
    "id": "cust_9981",
    "cedula": "100000000",
    "id_type": "fisica",
    "first_name": "María",
    "last_name": "López",
    "email": "maria.lopez@example.com",
    "phone": "80000000",
    "phone_country_code": 506
  },
  "line_items": null,
  "payer": {
    "cedula": "100000000",
    "name": "NOMBRE APELLIDO"
  },
  "sinpe_transaction_id": "SNP-9920141",
  "confirmed_at": "2026-08-05T20:10:00Z",
  "payment_link": {
    "code": "plk_a1b2c3d4e5f60718",
    "reference": "INV-2025-001",
    "additional_reference": "PO-88234",
    "amount_net": 25000,
    "iva_rate": 13,
    "iva_amount": 3250,
    "amount_total": 28250,
    "paid_at": "2026-08-05T20:10:00Z",
    "sinpe_ref": "SNP-9920141",
    "transaction_id": "9920141"
  }
}

Reading the payload

Payload versions

Two payload shapes exist. You stay on whichever you were created with — we never change it under you, because the signature is computed over the exact body bytes, so a shape change would break your parser and your verification at the same moment.

Every delivery carries X-Olanzo-Webhook-Version so you can tell them apart, and X-Olanzo-Event-Id for deduplication. To switch, set webhook_api_version on your business configuration (or ask support). Test both shapes with the test endpoint before you move.

Version 2026-08-06 envelope

{
  "event_id": "evt_9a174eb7c3f24b1d8e0a5c72",
  "event_type": "payment.confirmed",
  "created_at": "2026-08-05T20:10:00Z",
  "is_test_mode": true,
  "data": {
    "payment_link": { "link_code": "plk_a1b2c3d4e5f60718", "reference": "INV-2025-001", "order_id": "PL-AB23CD45" },
    "session": {
      "session_id": "9b1deb4d-3b7d-4169-9c47-c0e60807b5a1",
      "session_code": "cs_9b1deb4d3b7d41699c47c0e60807b5a1"
    },
    "payment": {
      "amount": 28250,
      "currency": "CRC",
      "order_reference": "INV-2025-001",
      "order_id": "PL-AB23CD45",
      "sinpe_transaction_id": "SNP-9920141",
      "confirmed_at": "2026-08-05T20:10:00Z",
      "payer": { "cedula": "100000000", "name": "NOMBRE APELLIDO" }
    },
    "customer": { "id": "cust_9981", "first_name": "María", "country_code": 506, "phone": "80000000" },
    "metadata": { "invoice_id": "inv_8492" },
    "amounts": { "amount_net": 25000, "iva_amount": 3250, "amount_total": 28250 }
  }
}

Payment-link lifecycle events (version 2026-08-06 only)

These remove the need to poll for anything except an unexpected silence.

Their data.payment_link carries the full link — status, all four amounts, and the timestamps.

Verifying the signature

Every delivery carries X-Olanzo-Signature: sha256=<hex>, and — regardless of version — also the replay-resistant X-Olanzo-Signature-V2: t=<unix>,v1=<hex> plus X-Olanzo-Timestamp. Prefer V2; the original header is kept so nothing breaks.

// Node.js — the V2 (replay-resistant) check.
const raw = req.body;                                   // Buffer, NOT the parsed object
const header = req.header("X-Olanzo-Signature-V2");     // "t=1754...,v1=abc..."
const { t, v1 } = Object.fromEntries(header.split(",").map(p => p.split("=")));

if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);

const expected = crypto
  .createHmac("sha256", process.env.OLANZO_WEBHOOK_SECRET)
  .update(`${t}.${raw}`)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.sendStatus(400);
res.sendStatus(200);

The rules below apply to both headers.

• Algorithm: HMAC-SHA256, lowercase hexadecimal.
• Key: your webhook signing secret, shown with your API keys in the Olanzo Portal under Create → Merchant → your business → E-commerce → API Keys. Test and live keys have different secrets.
• Signed content: the raw request body bytes, exactly as received. Do not parse and re-serialize the JSON first — key order and whitespace matter, and any reformat will fail verification.
• Comparison: use a constant-time comparison.

// Node.js (Express) — capture the RAW body, not the parsed object.
app.post("/webhooks/olanzo",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const expected = crypto
      .createHmac("sha256", process.env.OLANZO_WEBHOOK_SECRET)
      .update(req.body)              // Buffer of raw bytes
      .digest("hex");
    const received = (req.header("X-Olanzo-Signature") || "").replace(/^sha256=/, "");

    const ok = expected.length === received.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
    if (!ok) return res.sendStatus(400);

    res.sendStatus(200);             // acknowledge FIRST, then process asynchronously
  });

Delivery behaviour

Testing webhooks on this environment

Send yourself a real, signed sample event — same delivery path, same signature, same retry behaviour as a genuine payment, so it proves your endpoint and your verification actually work:

curl -X POST "http://checkoutapi-dev.jirafix.net/v1/payments/webhooks/test" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

{
  "delivered": true,
  "url": "https://your-site.example/webhooks/olanzo",
  "event_type": "payment_link.paid",
  "event_id": "evt_9a174eb7c3f24b1d8e0a5c72",
  "webhook_api_version": "2026-08-06",
  "http_status": 200,
  "note": "Your endpoint acknowledged the event.",
  "request_id": "req_71d11cfe"
}

The sample link in the event is not saved, so a test send never appears in your links or your reporting. Available on webhook version 2026-08-06 only.

To exercise the real matcher end to end instead, create a link with a test key (sk_test_…), open it, and use the test controls on the hosted page to mark the payment as paid — that is the same code path a live payment takes.

19. Idempotency & Retries

A create request that times out has still, quite possibly, succeeded. Retrying it blindly is how a customer ends up with two invoices for one order. Send an Idempotency-Key and the retry is absorbed.

Idempotency-Key: 98cf4fe7-eef4-48db-9ab5-e6a65d190b83

Supported on POST /v1/payments/payment-links and POST /v1/payments/checkout/sessions.

The key is echoed back in the Idempotency-Key response header. Keys are retained for the lifetime of the object they created, so a replay works for as long as the link exists.

reference is not a substitute for an idempotency key

Both prevent duplicates, but they answer different questions and behave differently.

20. Not Supported Yet

Stated plainly so you do not design around something that does not exist.

21. Testing Your Integration

There is no reserved test range. No card number, cédula, phone number or amount is treated specially by this API — there is no equivalent of a 4242… test card, and none is planned. An identification number is checked for shape only: the right digit count and prefix for a cédula física, jurídica or DIMEX, and 6–20 alphanumeric characters for a passport. Nothing verifies that the number was ever issued to anyone, so a made-up but correctly shaped value passes — use one. Do not test with a real person's identification; you gain nothing by it.

Your test key is what marks the session. Create the session with an sk_test_ key — creation always requires a secret key, so a publishable pk_ key is refused 403 here as everywhere else. What makes a session eligible for simulation is the key that created it, not the host it runs on: a test session gets the sandbox pipeline wherever it is served, and a live session can never reach it. Keeping test and live keys apart in your own configuration is what keeps a test run out of the merchant's reporting — the values inside the request will not do it for you.

The confirmation gate still applies in full in test mode: an unconfirmed link refuses every payment vector, the test-mode confirmation included (Confirming before paying).

22. Versioning & Breaking Changes

A breaking change carries six months' notice, counted from the day it is announced — not from the day it ships. You will always have two full quarters to move.

Announcements go out two ways, and you do not have to be watching for them:

• In the changelog, which is the durable record.
• By email to the contact registered against every API key. Keep that contact current; it is the only channel that reaches you without you looking.

Additive changes — a new optional field, a new value in an existing enumeration, a new endpoint — are not breaking and ship without that notice. Build your client so an unknown field or an unrecognised status is ignored rather than fatal, and additive changes will never reach you as an outage. Webhook payloads carry their own version; see Webhook Versions.

23. Support

support@olanzo.com — the same address the merchant portal shows. Staffed Monday to Friday, 08:00–17:00 Costa Rica time (UTC−6).

No response-time commitment is published yet. Said plainly so you can plan around it: if your launch depends on a guaranteed turnaround, raise that with your account contact rather than assuming one exists. Outside those hours, mail still arrives — it is read the next working day.

Include these and the first reply is far more likely to be the useful one:

• The request_id from the response, if you have it — it identifies the exact call in our logs.
• The environment you were on, and the session_code or link_code involved.
• The time, with its offset.

Never send us a secret key, in an email or anywhere else. We never ask for one, and no support question needs it. If a key has been exposed, rotate it in the portal first and tell us afterwards.

24. Security & PCI

No card data is handled anywhere in this API. SINPE Móvil moves money between bank accounts by phone number; there is no card number, expiry or CVV in any request, response, webhook or stored record, because there is no card in the flow at all.

We do not publish a PCI DSS self-assessment questionnaire classification. An SAQ level describes a merchant's own card-processing environment, and yours is not determined by us — confirm your scope with your acquirer or your assessor. What we can tell you, and what is usually the answer they need, is the sentence above: integrating this API does not introduce card data into your environment.

What is worth checking on your side:

• Secret keys stay server-side. A pk_ publishable key is the only one that belongs in a browser, and the API refuses a pk_ key on every secret-key route with 403.
• Verify the X-Olanzo-Signature-V2 header on every webhook and reject anything outside the timestamp tolerance — an unverified webhook endpoint is the one part of this integration an outsider can reach directly (§18).
• A cédula is personal data, and only some of it is masked for you. The value a payer types at the confirmation gate comes back masked, as confirmed_cedula_masked. A cédula you supplied on a link is returned to you in full as customer.cedula, and webhook payloads carry customer and payer identification in full — they have to, because that is what you match against. Treat everything you receive as personal data in your own storage, logs and support tooling; do not assume it arrived masked.