Making Payments

Learn how to create payments for usage with Checkout SDK or direct API calls.

Based on the Payment Flow Overview, the first step is to create a payment. This operation is strictly BE-to-BE and meant to be performed by the merchant's backend server using a Secret API Key.

Creating a Payment

important

Creating a payment does not charge the customer or reserve any funds, the payment stays in the open state until it is authorized.

We encourage you to create a payment early in the checkout flow, for example when the customer opens the checkout page or opens up the offer details. This way you can ensure that the payment is ready for authorization when the customer is ready to pay.

The process of creating a payment is the first step in the payment flow, in which you configure the payment details, such as the amount, currency, and payment method options. It is mandatory that a payment is first created before it can be authorized.

To create a payment, you need to send a POST /payments request. Many of the fields are optional and can be omitted based on your use-case. Any payment, however, requires the following:

amount: Payment amount in minor currency, for example 1000 for 10.00 USD. Must be either provided directly in the request body or derived from the payment.cart.items array.
currency: The currency of the payment, for example usd or eur.
initiator: Indicates whether the payment is initiated by the merchant or the customer, defaults to customer. Note that merchant-initiated payments will fail immediately if any customer action, such as 3DS authentication, is required.
paymentMethodOptions: An object containing the payment method options. This is required if you want to specify a particular Gateway Profile or Cascade to use for the payment. If not specified, the defaults from the Merchant Configuration will be used, if no defaults are set, the payment won't be created.

tip

If a payment method (such as card or paypal) is not present in paymentMethodOptions and there's no defaults in the Merchant Configuration, the payment will still be created, but the missing payment method will not be available for payment authorization.

By default, the payment will be created with no customer or payment method, expecting them to be provided during authorization at a later step. In many cases, however, you will want to make the payment with a saved payment method, for example for a returning customer. In this case, you can provide the following optional fields:

paymentMethod: The ID of the payment method to be used for the payment. Can only be provided together with the customer who this payment method belongs to.
customer: The ID of the customer who is making the payment. If paymentMethod is not provided and paymentMethodOptions.useCustomerDefault is true, the default payment method for this customer will be used, if no default payment exists, the payment method will be left empty.

Example request bodies

The most common scenario is creating a payment using pre-configured Odus Prices. They should be passed to the cart.items array and provide the IDs of said prices. Note that the amount field is not required in this case, as it will be derived from the prices in the cart. You can also optionally overwrite the amount for each individual item in the cart.

Creating a payment with cart
{
  "currency": "usd",
  "initiator": "customer",
  "paymentMethodOptions": {
    "card": {
      "mode": "cascade",
      "cascade": "cas_xyz123"
    }
  },
  "cart": {
    "items": [
      {
        "price": "price_abc321",
        "quantity": 1
      },
      {
        "price": "price_def654",
        "quantity": 1,
        "amount": 1999
      }
    ]
  }
}

Providing multiple payment methods is just as simple, you just need to specify the gatewayProfile or cascade in the paymentMethodOptions for each payment method you want to use. If you don't specify a payment method, the defaults from the Merchant Configuration will be used.

Creating a payment with multiple payment methods
{
  "amount": 1000,
  "currency": "eur",
  "initiator": "customer",
  "paymentMethodOptions": {
    "card": {
      "mode": "cascade",
      "cascade": "cas_abc123"
    },
    "paypal": {
      "mode": "direct",
      "gatewayProfile": "gwp_xyz456"
    }
  }
}

To create a payment with a saved payment method, you need to provide the customer and paymentMethod fields. The payment method must belong to the customer, otherwise the request will fail.

Creating a payment with a saved payment method
{
  "amount": 5000,
  "currency": "usd",
  "initiator": "customer",
  "paymentMethodOptions": {
    "card": {
      "mode": "cascade",
      "cascade": "cas_abc123"
    }
  },
  "customer": "cus_123456",
  "paymentMethod": "pm_789012"
}

To use customer's default payment method, we only need to provide the customer field and set paymentMethodOptions.useCustomerDefault to true. This will automatically use the customer's default payment method for the payment, if it exists. If no default payment method is set for the customer, the payment will fail during authorization.

note

Setting paymentMethodOptions.useCustomerDefault to true will pick any default payment method for the customer, regardless of the payment method type (e.g. card, PayPal, etc.)

To Ensure that the customer can pay, you should set default gateways and cascades in the Merchant Configuration for each payment method type. This way, if the customer has a default payment method, it will be used automatically without requiring any additional configuration.

Creating a payment with customer's default payment method
{
  "amount": 2500,
  "currency": "eur",
  "initiator": "customer",
  "paymentMethodOptions": {
    "useCustomerDefault": true,
    "card": {
      "mode": "cascade",
      "cascade": "cas_abc123"
    }
  },
  "customer": "cus_123456"
}

A customer-initiated payment can also be created with just two parameters: amount and currency, the rest will be derived from the Merchant Configuration. This is useful for one-off payments or when you don't want to integrate with Odus Prices.

Creating a payment with just amount and currency
{
  "amount": 1500,
  "currency": "eur"
}

Authorizing a Payment

After successfully creating a payment, the next step is to authorize it by sending a POST /payments/:paymentId/authorize request. This is where the actual payment is processed, and the customer is charged or funds are reserved. There are several ways to authorize a payment, depending on whether you want to use a saved payment method or require the customer to enter their payment details, they are:

Directly using the API: Can only be used when using a saved payment method and is the preferred way to pay for returning customers. Note that even though such payments normally do not require any customer interaction, it is possible that the customer's bank requests 3DS authentication. Such payments will be marked as requires_action and you can either complete the 3DS by redirecting customer to the payment.action.redirectUrl or consider the payment failed.
Using the Checkout SDK: This is the only way to authorize a payment when the customer needs to enter their payment details, for example when paying with a new card or PayPal. The Checkout SDK will handle the customer interaction and 3DS authentication if required.

note

Authorizing a payment with raw card details is not allowed. You must use the Checkout SDK which will securely collect the card details leaving you out of PCI-DSS compliance scope. If you need to authorize a payment with a saved card, you can use the API directly as described above.

Authorizing using the API

To authorize a payment via the API, first you need to ensure that it was created with a saved payment method as described above. Then you can send a POST /payments/:paymentId/authorize request. Keep in mind that there's a slight distinction between authorizing a merchant-initiated payment and a customer-initiated payment

For all customer-initiated payments, you must provide a valid context.returnUrl, which will be used to redirect the customer after they complete the redirect flow. As mentioned above, you may choose to not redirect the customer at all, in which case you can provide any valid URL, such as your website's homepage.

For merchant-initiated payments, the context is ignored and the payment will automatically fail if any customer interaction is required.

Assuming we created a payment with a saved payment method, the request body for authorizing it would look like this:

Authorizing a payment with a saved payment method
{
  "context": {
    "returnUrl": "https://example.com/return"
  }
}

Authorizing using the Checkout SDK

warning

Redirect flows such as 3DS Authentication or PayPal require special handling by your application for optimal user experience. You can read more about it in the Handling Redirects guide.

To authorize a payment when the customer needs to enter their payment details (new card, PayPal, etc.), you must use the Checkout SDK. The SDK securely collects payment information and handles 3DS authentication automatically.

For complete setup instructions, code examples, and configuration options, refer to the Checkout SDK Getting Started guide.

Creating a Payment​

Example request bodies​

Authorizing a Payment​

Authorizing using the API​

Authorizing using the Checkout SDK​

Creating a Payment

Example request bodies

Authorizing a Payment

Authorizing using the API

Authorizing using the Checkout SDK