Docs
Payments
Collect a Payment
Online Payments

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_url that 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

STATUSDESCRIPTIONADDITIONAL INFORMATION
requires_payment_methodPayment requires a payment methodIf a payment attempt fails, it reverts to this status.
requires_confirmationPayment method has been provided but the payment requires confirmationThis 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_capturePayment has been authorized but not capturedUsed when authorization and capture are separate actions.
requires_actionPayment requires additional actionFor example, action needs to be taken on the terminal to complete the payment.
processingPayment is processingProcessing time varies by payment method.
succeededPayment has succeededA ChargeAPI object has been created and funds are in the merchant’s account. If several payment attempts were made, several charges would exist.
canceledPayment has been canceledA 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.

FAQ

What is the difference between a payment intent and a charge?A payment intent represents the entire lifecycle of a payment, from initiation to completion or cancellation. In contrast, charges occur at a singular point in the payment process when a transfer of funds is initiated.
Is it possible to perform more than one capture with the same payment intent?No, a payment intent can only be captured once even if the captured amount is less than the authorized amount.
What payment methods are supported?Card, bank-to-bank, and Apple Pay are supported for online payments. HSA/FSA cards are not supported at this time.
What card brands are supported?Visa, Mastercard, Discover, and Amex are supported, with Maestro, Diners, and JCB also available with Paysafe.