Search

Are you looking for test card numbers?

Would you like to contact support?

Online-payment icon

Partial payments

Let your shoppers make a purchase with multiple payment methods using our Checkout Order API.

Try it!
Use the Checkout Order API to let your shoppers make payments with their gift cards along with other payment methods.

The Checkout Order API offers full flexibility in combining different payment methods to let your shoppers make payments.

A shopper can pay for a product using multiple payment method options, for example, when a shopper uses a gift card with an insufficient balance for their purchase. When the shopper pays the total amount of the order, we close the order and send a webhook notification to you.

You can create an order when a shopper wants to use multiple payment methods to pay for a product in their shopping cart. For example, you can create an order when your shopper wants to use two different gift cards, and a credit card to make a payment.

Create an order

To create an order:

  1. Make a POST /orders request, and specify:

    Parameter Required Description
    amount -white_check_mark- The currency and value of the payment (in minor units). For more information, see Currency codes.
    reference -white_check_mark- Your unique identifier for this order.
    expiresAt The automatic expiry time for the order. When not set, it defaults to 24 hours after the creation date. The expiresAt field is specified in ISO 8601. For example, 2019-01-01T14:21:00.
    POST /orders
    {
      "reference": "YOUR_ORDER_REFERENCE",
      "amount": {
        "value": 2500,
        "currency": "EUR"
      },
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
    }
    Response
    {
      "pspReference": "8815517812932012",
      "resultCode": "Success",
      "reference": "YOUR_ORDER_REFERENCE",
      "remainingAmount": {
        "value": 2500,
        "currency": "EUR"
      },
      "expiresAt": "2019-01-01T14:21:00",
      "orderData": "823fh892f8f18f4...148f13f9f3f"
    }
  2. Store the pspReference and orderData to make payments. The orderData contains the state of the order. You need to include this value with your /payments request for every payment in the order. This updates the amount to be paid in the order.

Make a payment

To make a payment, additionally include the previously stored pspReference and orderData within the order object in the /payments request. If you're paying with a redirect payment method, see Redirect payment method.

POST /payments
{
  "reference": "YOUR_PAYMENT_REFERENCE",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "paymentMethod": {
    "type": "givex",
    "number": "4126491073027401",
    "cvc": "737"
  },
  "order": {
    "{hint:pspReference from /orders response}pspReference{/hint}": "8815517812932012",
    "orderData": "823fh892f8f18f4...148f13f9f3f"
  },
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
Response
{
  "pspReference": "4827489798978324",
  "resultCode": "Authorised",
  "order": {
    "pspReference": "8815517812932012",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "remainingAmount": {
      "value": 1500,
      "currency": "EUR"
    },
    "expiresAt": "2019-01-01T14:21:00",
    "orderData": "111aa111a1a11a1...123a11a1a1a"
  }
}

In the response, you receive the status of the order in the order object. The order object includes the remaining amount required on the order, and an updated orderData value. Use the new orderData value to make follow-up payments.

Redirect payment method

In care of a redirect payment method, such as iDEAL:

  1. Make a POST /payments call, and include the order object containing the pspReference and orderData that you received in the /orders response.

    Redirect /payments request
    {
      "reference": "YOUR_PAYMENT_REFERENCE",
      "amount": {
        "value": 1000,
        "currency": "EUR"
      },
      "paymentMethod": {
        "type": "ideal",
        "issuer": "2498"
      },
      "order": {
        "pspReference": "8815517812932012",
        "orderData": "823fh892f8f18f4...148f13f9f3f"
      },
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy.."
    }
    Response
    {
      "resultCode": "RedirectShopper",
      "action": {
        "method": "GET",
        "paymentData": "Ab02b4c0!BQABAg...h+yVGCtjB",
        "paymentMethodType": "ideal",
        "type": "redirect",
        "url": "https://test.adyen.com/hpp/redirectIdeal.shtml?brandCode=ideal&currencyCode=EUR..."
        },
      "details": [
        {
          "key": "payload",
          "type": "text"
        }
      ],
      "pspReference": "4827489798978324"
    }
  2. Handle the redirect. To find the updated order object, make a POST /payments/details call, and include details. The details object contains the URL-decoded values of the parameters that were returned when the shopper was redirected back to your website or app. For example, payload.

    POST /payments/details call
    {
      "paymentData": "Ab02b4c0!BQABAg...h+yVGCtjB",
      "details": {
        "payload": "Ab02b4c0!21BQABAgCYm...Z1J0yK8xNzYrAQ3l7"
      },
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
    }
    Response with the updated order
    {
      "pspReference": "4827489798978324",
      "resultCode": "Authorised",
      "order": {
        "pspReference": "8815517812932012",
        "reference": "YOUR_PAYMENT_REFERENCE",
        "remainingAmount": {
          "value": 500,
          "currency": "EUR"
        },
        "expiresAt": "2019-01-01T14:21:00",
        "orderData": "111aa111a1a11a1...123a11a1a1a"
      }
    }

    Use the new orderData value to make follow-up payments.

Complete order

When the payment results in the order being fulfilled, a remainingAmount of 0 is returned. As this is the last payment, no orderData is returned for follow-up payments.

Response with order amount 0
{
  "pspReference": "4827489798978324",
  "resultCode": "Authorised",
  "order": {
    "pspReference": "8815517812932012",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "remainingAmount": {
      "value": 0,
      "currency": "EUR"
    },
    "expiresAt": "2019-01-01T14:21:00"
  }
}

A remaining amount of 0 does not indicate that the order is completed.

Notifications

When all payments in the order have reached a final state, we send an ORDER_CLOSED notification. The notification contains a success value that indicates whether all payments were completed successfully. For more details, see Notifications.

Cancel an order

You can cancel an order by making a POST /orders/cancel call. The order is also cancelled when it reaches expiry time. Cancellation of an order results in an automatic rollback of all payments made in the order, either by canceling or refunding the payment, depending on the type of payment method.

When canceling the order, submit the pspReference and orderData inside an order object.

POST /orders/cancel
{
  "order": {
    "pspReference": "8815517812932012",
    "orderData": "823fh892f8f18f4...148f13f9f3f"
  },
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
Response: Successful cancellation
{
  "pspReference": "8515518617625887",
  "resultCode": "Received"
}

Once an order has been canceled, we send the ORDER_CLOSED notification with its success value set to false.

Gift cards

You can use the Order API when your shopper chooses to pay with one or more gift cards. If your shopper's gift card has enough balance to pay for their purchase, then you can just make a POST /payments call.

If they use a gift card that doesn't have enough balance for the payment, then the gift card needs to be used along with another gift card or other payment methods (or both).

Check gift card balance

To check a gift card's balance, make a POST /paymentMethods/balance call and include the gift card's details inside a paymentMethod object.

POST /paymentMethods/balance
{
  "paymentMethod": {
    "type": "givex",
    "number": "4126491073027401",
    "cvc": "737"
  },
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}

In the response, we return a result code of Success, Failed, or NotAllowed. If the result code is NotAllowed, the gift card could still have balance, but it isn't available for the specific items the shopper is purchasing.

Response with Success result code
{
  "pspReference": "8515518617625887",
  "resultCode": "Success",
  "balance": {
    "value": 2500,
    "currency": "EUR"
  }
}
Response with Failed result code
{
  "pspReference": "8515518617625887",
  "resultCode": "Failed"
}