Online Payments
offers various options for collecting one-time, online payments:
- API-only: Build a custom payment flow using the Payment IntentsAPI.
- Checkout sessions: Low-code option for partners to generate
checkout_session_urlthat routes the customer to a -hosted payments page. - Payment links: No-code option for merchants to generate a unique payment link from the Dashboard that routes the customer to a -hosted payments page.
To determine which option is best for you, review our payment integration options.
Collect an Online Payment
Asynchronous payment flows are complex to manage because they depend on customer interactions that happen outside of your application. Payment IntentsAPI simplify this by tracking the payment status, serving as the source of truth throughout the payment lifecycle.
Create a payment intent
To Create a Payment IntentAPI, specify the necessary details such as currency, payment method, and amount.
curl -L '{{PRODUCTION_API_URL}}/v1/payment-intents' \
-H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
-H 'Content-Type: application/json' \
-H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
-d '{
"amount": 1000,
"currency": "usd",
"payment_method_types": [
"card"
],
"confirm": true,
"payment_method_id": "{{PAYMENT_METHOD_ID}}"
}'Best practices when creating a payment intent
- Create a Payment IntentAPI at the beginning of the checkout process, once you know the total amount. If the amount changes, you can Update a Payment IntentAPI as needed.
- If the checkout process is interrupted and later resumed, reuse the existing payment intent instead of creating a new one. Reusing the payment intent helps in monitoring any failed payment attempts and keeps the transaction history organized for each cart or session.
Confirm the payment
In order to confirm a payment intent, the payment method details or a payment_method_id must be specified. You can confirm at creation by setting confirm=true in the request body.
If the payment intent status is requires_payment_method, you'll need to attach a payment method using the Confirm a Payment IntentAPI endpoint.
curl -L '{{PRODUCTION_API_URL}}/v1/payment-intents/{{PAYMENT_INTENT_ID}}/confirm' \
-H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
-H 'Content-Type: application/json' \
-H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
-d '{
"payment_method_id": "{{PAYMENT_METHOD_ID}}"
}'Payment Intent States
| STATUS | DESCRIPTION | ADDITIONAL INFORMATION |
|---|---|---|
requires_payment_method | Payment requires a payment method | If a payment attempt fails, it reverts to this status. |
requires_confirmation | Payment method has been provided but the payment requires confirmation | This status is set after the customer provides payment information and before the payment intent is confirmed. Often bypassed in integrations where payment information and confirmation occur simultaneously. |
requires_capture | Payment has been authorized but not captured | Used when authorization and capture are separate actions. |
requires_action | Payment requires additional action | For example, action needs to be taken on the terminal to complete the payment. |
processing | Payment is processing | Processing time varies by payment method. |
succeeded | Payment has succeeded | A ChargeAPI object has been created and funds are in the merchant’s account. If several payment attempts were made, several charges would exist. |
canceled | Payment has been canceled | A payment intent can be canceled before it reaches processing or succeeded status, making it invalid for future attempts. This action is irreversible. Any held funds will be reversed. |