Card Payments (Hosted Checkout)

The hosted checkout is the simplest way to accept cards. You create a charge, redirect the customer to checkout_url, and we handle the card form, 3D Secure, Apple Pay and Google Pay. Settlement is in USD.

Before you start

• Card payments must be enabled and approved on your account (Settings, Card payments). Otherwise the API returns CARD_NOT_AVAILABLE (403) or STRIPE_ACCOUNT_NOT_READY (422).
• Minimum charge: USD 5.00.
• Sandbox credentials (tk_test_ / sk_test_) work for the whole card flow.

1. Create the charge

POST /wallet/deposit/payment with method_pay=card.

{
  "token": "YOUR_TOKEN",
  "secret": "YOUR_SECRET",
  "amount": 100.00,
  "method_pay": "card",
  "postback": "https://example.com/callbacks/card",
  "return_url": "https://example.com/orders/1042/thanks",
  "debtor_name": "John Doe",
  "email": "[email protected]"
}

Do not send placeholder customer data. When you omit name and email, Apple Pay and Google Pay fill them from the wallet. Values you send are kept and never overwritten by the wallet.

Response (200)

{
  "status": "ok",
  "idTransaction": "3f2b8c1e-7a4d-4e3b-9c2a-1d5e6f7a8b9c",
  "checkout_url": "https://dominipay.com/checkout/cartao/3f2b8c1e-7a4d-4e3b-9c2a-1d5e6f7a8b9c",
  "amount": 100.00,
  "currency": "usd",
  "expires_in_seconds": 1800,
  "client_secret": "pi_3TestExample0000000001_secret_TestExample",
  "publishable_key": "pk_test_YOUR_PUBLISHABLE_KEY",
  "on_behalf_of": "acct_1TestExample00000"
}

• Redirect the customer to checkout_url.
• Store idTransaction to match callbacks and status checks.
• expires_in_seconds: how long the session stays open. After that the charge is cancelled and you get a cancelled callback.
• client_secret, publishable_key and on_behalf_of are only needed if you embed Apple Pay or Google Pay on your own page. Ignore them for the redirect flow.

checkout_url may use your own checkout domain if one is configured for your account.

2. The customer pays

On the hosted page the customer enters a card or uses Apple Pay or Google Pay. 3D Secure runs when the bank asks for it.

A declined attempt does not end the session. The customer can try another card on the same transaction until the session expires. While that is possible, the status stays pending.

After a successful payment the customer sees a confirmation page with a button back to your return_url and is redirected there automatically after 5 seconds.

3. Fulfill the order

When the payment is confirmed, the net amount (after the platform fee) is credited to your USD balance and we POST to your postback:

{
  "status": "paid",
  "idTransaction": "3f2b8c1e-7a4d-4e3b-9c2a-1d5e6f7a8b9c",
  "typeTransaction": "CARD",
  "amount": 100.00,
  "currency": "USD"
}

Fulfill on paid. Do not fulfill because the customer reached your return_url; the redirect is not proof of payment.

If the session ends without payment:

{
  "status": "cancelled",
  "idTransaction": "3f2b8c1e-7a4d-4e3b-9c2a-1d5e6f7a8b9c",
  "typeTransaction": "CARD",
  "amount": 100.00,
  "currency": "USD",
  "failure_code": "expired",
  "message": "Payment session expired (not completed within timeout)."
}

failure_code is expired when nobody tried to pay, or the decline code of the last attempt (with decline_code set) when the customer tried and failed.

Later the charge can also receive refunded, partially_refunded, disputed, dispute_won and dispute_lost callbacks. See Webhooks.

Checking status

GET /transactions/payment/{idTransaction} returns the card status, amounts, card brand and last 4 digits, refunds and dispute details. Read failure_is_final before acting on failure_code. See Transaction status.

Embedding the checkout in an iframe

By default the hosted page cannot be framed by other sites. To open it in an iframe, ask support to add your site origin (https only, for example https://shop.example.com) to the allowed frame ancestors. Your iframe must include allow="payment" for Apple Pay and Google Pay to work:

<iframe src="CHECKOUT_URL" allow="payment" width="100%" height="720"></iframe>

Errors

See Error codes for the full list.

Withdrawing the USD balance

The USD balance is separate from your BRL balance. Request USD withdrawals from the dashboard (Card payments, USD withdrawals). They are settled in crypto to a wallet you provide.