Skip to main content
Card Checkout lets the customers on your account accept card payments from their own buyers. You verify each selling customer once, create an order for the amount through the API, and send the buyer to the returned checkout_url. Yativo hosts the payment page, runs 3-D Secure when the buyer’s bank asks for it, and sends you a webhook for every change in the order.
  • You set the amount when you create the order. The buyer can’t change it.
  • Card details are entered in secure, isolated fields. They never reach your servers.
  • Only the card_checkout.order.paid webhook means the buyer paid. A buyer reaching your success_url isn’t proof of payment: browsers close, redirects fail and URLs can be typed by hand.

​
Before you start

Every request uses your API key (X-Api-Key and X-Api-Secret), and your Yativo account must have passed KYC. Send an Idempotency-Key header on every POST so a retried request never runs twice.
  • Amounts are decimal strings in major units, for example "49.99".
  • Only USD is enabled today.
  • The status codes on this page are the status_code in the response body.

​
Request access

Card Checkout must be enabled for your account. Until it is, every other endpoint on this page returns 403 with code: card_checkout_not_enabled.
note is optional (up to 1,000 characters): tell us what your customers sell and to whom. The response is your account with access_status: "requested" (202). Sending the request again while it’s open changes nothing. If access is already enabled you get 200 with access_status: "enabled". Your pricing (fee, settlement delay, reserve and currencies) is set when access is granted. Read it with GET /card-checkout/account.

​
Step 1: Verify the customers who sell

Each customer that sells by card needs an approved card_checkout endorsement, next to its other endorsements. Individual and business customers can both be endorsed.

​
Submit the endorsement

No body. Yativo reuses what the customer already submitted:
  • Business customer: its KYB details (legal name, entity type, tax and registration numbers, registered address and the signer). The customer then uploads company documents on the onboarding page.
  • Individual customer: its KYC details. If its ID photos and a selfie are already on file they’re used straight away. Otherwise the customer confirms the prefilled details and adds the photos on the onboarding page.
Response
Send the customer to onboarding_url. The Yativo-hosted page shows only the form for the customer’s type, prefilled with what’s on file. If the review needs more, such as a clearer photo, the same page lists each item and collects the answers. You can also submit it with the endpoint you use for other endorsements: POST /customer/kyc/resubmit/{customer_id}/card_checkout. For card_checkout it accepts business customers too. Submitting again is safe: an approved customer is left as it is.
If a customer asks for card checkout before your account has access, the request is held, not refused. Yativo files an access request for you, the endorsement becomes pending with metadata.awaiting_business_access: true, and the response is 202 with awaiting_business_access: true. Once your account is enabled, waiting customers are submitted automatically. If your access request was declined, the endorsement returns 403 with code: card_checkout_access_declined.

​
Follow the endorsement

Every change sends the usual endorsement.updated webhook. The endorsement also appears on the customer (GET /customer/{customer_id}); while the customer has something to do, its hosted_kyc_url holds a working onboarding link. To read it on its own:
The response has the same shape as the submit response.
Both fields are optional https URLs. return_url is the Back to app link on the page; refresh_url is where the customer lands after the link expires. The response has customer_id, endorsement_status, onboarding_url and expires_at. The link is valid for 2 hours.

​
Or verify a business customer with your own form

If you’d rather collect business details in your own app, use the verification endpoints. Individual customers always add their ID and selfie on the onboarding page.
1

Get the prefilled form

GET /card-checkout/customers/{customer_id}/verification returns kind (business or individual), verification.verification_status, prefill (the details on file), missing_fields and the allowed business_structures. The tax identification number is never prefilled.
2

Submit corrections

POST /card-checkout/customers/{customer_id}/verification with kind: "business". Any field you leave out is taken from prefill; a field you send overrides it. The response (201) has verification_status and, when the review needs more, information_requested.
3

Answer what the review asks for

POST /card-checkout/customers/{customer_id}/verification/information as multipart/form-data, one answer per item in information_requested. Answered items leave the list; you can answer some now and the rest later.
Fields for POST .../verification: Each item in information_requested has an id (send it back with the answer), a requirement (for example business_verification_document, identity_document, ein), a type that says how to answer, a label to show the user, and optionally options, multiple, optional, files_allowed and errors (why a previous answer was rejected). ID document slots: PASSPORT → passport_front; ID_CARD → id_card_front, id_card_back; DRIVERS → drivers_front, drivers_back; RESIDENCE_PERMIT → residence_permit_front, residence_permit_back. Files are JPG, PNG or PDF, up to 10 MB each and 10 per item (a selfie must be JPG or PNG). Everything is checked before anything is sent, so one bad answer sends nothing.
Other countries have no structures: send business_name and leave out business_structure.

​
Step 2: Create an order

  • platform_fee, reserve and net_amount are fixed when the order is created. Later pricing changes don’t affect it.
  • The checkout link expires after 60 minutes (expires_at). Create a new order if the buyer comes back later.
  • When you limit payment_methods, the order includes them.

​
Step 3: Send the buyer to the checkout page

Redirect the buyer to checkout_url exactly as returned. The URL is signed, so any change makes it invalid. On the checkout page, which shows your customer as the seller, the buyer enters their email, name, billing address and card details, completes 3-D Secure if their bank asks, and lands on a receipt page with a link to your success_url. The page works on mobile and in light and dark mode.
To protect you and your customers from fraud, the checkout page records the buyer’s actions on the page, device and browser details, IP address and approximate location, and tells the buyer it does. The record is used for fraud review and dispute evidence.

​
Step 4: Follow orders with webhooks

Card Checkout events go to your registered webhook URL and are signed like every other event. You get one for every status change and every refund or dispute amount change. The payload is the order:
Make your handler idempotent: an event can arrive more than once, and events can arrive out of order. When in doubt, read the order and act on its status.

​
Read orders

GET /card-checkout/orders/{id} returns the order. While the order can still be paid it includes a fresh checkout_url. The list is paginated: data holds the orders and pagination has current_page, per_page, total and last_page. Another account’s order returns 404.

​
Your account and balance

Response

​
Let a customer withdraw their sales

The response has customer_id, withdrawal_url and expires_at. Send the customer to withdrawal_url to withdraw their card sales. return_url and refresh_url are optional and must be https. The customer needs a submitted card_checkout endorsement, or the request returns 409 with code: endorsement_not_submitted.

​
Fees, settlement and reserves

For every paid order:
  • Clearing. net_amount is recorded against the selling customer when the payment is confirmed and becomes available after clearing_business_days US business days. Until then it’s on_hold.
  • Reserve. If your account has a reserve, that part becomes available after retention_days.

​
Refunds and disputes

Refunds and chargebacks come out of the balance of the customer that made the sale.
  • The refunded or disputed amount is deducted. If that makes the balance negative, later sales cover it.
  • A disputed amount is deducted when the dispute opens and credited back if you win. Pre-dispute inquiries don’t move funds.
  • The platform fee on a refunded order isn’t returned.

​
Errors

Card Checkout errors include a code in data next to the message. See Error response format for the full response.

​
Test in sandbox

Use your sandbox API key and these test cards, with any future expiry date, any 3-digit CVC and any billing address: To test your webhook handler without creating an order, send a sample event with POST /demo/webhook/card_checkout (defaults to card_checkout.order.paid) or POST /demo/webhook/card_checkout.order.expired.