Integrate YeboPay · Reviewed 24 October 2026

API keys, hosted checkout and webhooks

Start safely with sandbox charges, discover methods, create checkout links and verify signed events.

Create and protect API keys

Open Developers. Choose Live or Test data before creating a key, name it and grant only the scopes required for the integration. Copy the one-time plaintext key into server secret storage; use the prefix and dialog mode to confirm whether it is a test credential. Do not put API keys in frontend code.

Follow the existing first sandbox payment tutorial for screenshots and a complete simulated charge. Test keys use the production API host, with the key selecting mode. Escrow and live-only operations have separate limits.

Direct charges and hosted checkout

Surface	Use it for	Endpoints
Direct charge	A supported saved method or one-off provider collection.	`POST /v1/charges` · `GET /v1/charges/{id}`
Hosted checkout	A payment page the customer opens to complete the payment.	`POST /v1/checkouts` · `GET /v1/checkouts/{id}`
Provider discovery	Current active methods for a country.	`GET /v1/payment-options`
Disbursement	A supported outgoing provider payment.	`POST /v1/disbursements` · `GET /v1/disbursements/{id}`

Developers also contains hosted Checkout sessions. Inspect the session and actual charge state. A browser redirect or successful request creation does not establish settlement. Keep one idempotency key for each logical operation when the endpoint supports it, and reconcile amount, currency, merchant and order before fulfillment.

Handle signed events and delivery failures

Configure the public HTTPS webhook endpoint and signing secret in Developers → Webhooks.
Verify the signature against the raw request body before trusting an event. Use the signature contract in the API reference and keep secrets on the server.
Deduplicate by event ID. Match the merchant, object, amount and currency, then update the corresponding order once.
Inspect Delivery log for response codes, retries and failures. Confirm your handler updated the order as well as returning an HTTP success.

See the API reference for documented request and response schemas. Use the escrow operations guide and billing guide for capabilities not yet represented in the interactive schema.

Additional API capabilities

Saved payment-method setup and removal, charge refunds, payout status, channel inspection and FX estimates are implemented integration surfaces. Method/provider support, scopes, merchant activation and mode determine whether an operation is available. A saved method is not a guarantee of recurring debit support, an FX estimate is not a settled conversion, and a refund request is not proof of provider completion.

The membership register supports gated member lookup with a second factor, invoice allocation and customer identity operations. It is an integration capability with merchant-specific enablement, not a generally available dashboard member portal. The legacy bank-receipt reconciliation endpoint is distinct from current dashboard proof review; confirm provider readiness before adopting it.

Manage saved payment methods

These are server integration operations. With the required charges.write scope, use POST /v1/payment-methods/setup to start supported card setup, complete the customer authorization in the provider UI, then call POST /v1/payment-methods/vault-card so the server verifies the setup result. Use the returned saved method ID for eligible charges or subscriptions.

List customer methods with GET /v1/payment-methods?customer=YEBOID_SUB (replace the placeholder with the customer’s UUID), update label/default with PATCH /v1/payment-methods/{id}, and deactivate with DELETE /v1/payment-methods/{id}. General provider vaulting also uses POST /v1/payment-methods. Never collect raw card details on your server or treat client-supplied card metadata as verification.

Vaulting requires live merchant eligibility and a provider that supports the operation. An unsupported recurring vault flow returns 422 vaulting_unsupported. Do not assume a test charge key makes card vaulting simulated.

Read reference exchange rates

Use GET /v1/fx/rates?symbols=SZL,KES with an API key. Read base, rates, source and updated_at. The base is USD and each rate is units of that currency per USD. These reference values are not a guaranteed settled conversion.

Stale rates are omitted. If a required currency is missing or the rate map is empty, show that the estimate is unavailable and resolve the data outage. Do not substitute a constant rate.

Membership register integrations

The gated register can look up a customer by membership reference and a configured second factor, then allocate payment against outstanding invoices oldest due first. Merchant setup and verification rules determine availability. It is not a complete self-service member portal in the current dashboard.

Customer merging and undo are controlled identity operations. Review duplicate identities and invoice ownership before invoking them; a matching name is not enough. Work with the merchant’s enabled register contract before implementing lookup, payment or proof submission.

Explore the other features

Browse all guides