Skip to main content

Create and confirm your first payment

Create and retrieve a Checkout to complete your first payment without depending on Webhooks. Before starting, confirm your test account can create and retrieve Checkouts; see availability. Requests use the documented test URL; replace all keys, orders and illustrative responses with your own test data.

1. Prepare the server​

You need curl, a test API Key and durable order/payment-attempt storage. Environment variables below are illustrative. Production hosts should use key management and reload persisted idempotency keys from storage.

export API_BASE='https://connect-dev.invisipay.fi'
export API_KEY='inv_test_REPLACE_WITH_YOUR_SERVER_KEY'
export CHECKOUT_CREATE_KEY='550e8400-e29b-41d4-a716-446655440000'

Create a new key for each new operation; retain the original key and parameters for retries. Persist the order, expected amount/currency, body and key in a transaction before sending. Never place merchant keys in browser/mobile clients.

2. Inspect payment methods​

curl --fail-with-body --silent --show-error \
"$API_BASE/v1/payment-methods" \
-H "Authorization: Bearer $API_KEY"

ipp (IPP payment) and erc20_transfer (direct ERC-20 transfer) are payment methods. Each response group lists the complete currency/network pairs supported by that method. Use returned combinations rather than independently combining currencies and networks. See payment methods.

The following example uses USDC. Before continuing, confirm at least one returned payment-method group supports a usdc/network pair. Otherwise confirm account support or adapt the amount and request to the actual supported order currency.

3. Create a Checkout​

A Checkout is one collection session. Derive amounts from trusted server-side order data, not a browser-supplied price. "10" means 10 USDC, not base units.

curl --fail-with-body --silent --show-error \
"$API_BASE/v1/checkouts" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $CHECKOUT_CREATE_KEY" \
--data '{"amount":"10","currency":"usdc","order_id":"ORDER_001","description":"Order payment"}'

This response fragment uses illustrative identifiers and URL; it is not usable for real collection or retrieval:

{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"order_id": "ORDER_001",
"status": "open",
"exception_status": null,
"url": "https://pay.example.com/c/checkout_example"
}

Persist the actual id and url against the payment attempt. Multiple Checkouts can reference one order; order_id is not an API deduplication guarantee. See create Checkout for required parameters and responses.

4. Share the cashier URL​

Give the actual returned url to the order’s payer. return_url is only the cashier’s return-button target, not proof of payment or an automatic redirect. Authenticate order access before retrieving its locally associated Checkout.

5. Retrieve and confirm​

Replace CHECKOUT_ID with the actual returned ID. This example assumes an ID without reserved characters; general clients must encode path IDs.

export CHECKOUT_ID='REPLACE_WITH_THE_RETURNED_CHECKOUT_ID'
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/checkouts/$CHECKOUT_ID" \
-H "Authorization: Bearer $API_KEY"
ResultBusiness action
openShow waiting for payment and query server-side within rate limits
processingPayment is on chain awaiting confirmation; show progress without asking for another payment
succeeded with matching order, currency and amountEvaluate exceptions and fulfill once per business order
failedStop treating this session as a payable collection; handle its failure reason
Non-null exception_statusHandle fund exceptions independently of primary status
Timeout or HTTP errorOutcome is unknown; recover retrieval rather than immediately collecting again

Read states and exceptions and confirmation and fulfillment for reusable server-side examples.

6. Test before extending​

Exercise repeated clicks, creation timeouts, restarts and multiple Checkouts per order without duplicate fulfillment. Add Webhook processing after enablement, retaining query recovery. Refunds and settlements have their own availability; working collection APIs do not imply those features are usable.