Skip to main content

Payment Setup

POST 
/v2/orders/:orderID/payments

Depending on the payment gateway, you may have access to different transaction types such as capturing funds immediately or authorizing them for later. For more information, see Transactions.

The following types of payment methods are available depending on the payment gateway:

  • purchase: The is the simplest method. The gateway attempts to charge the customer immediately.
  • authorize: This method authorizes a payment so that funds can be captured later, for example, when an item is dispatched or restocked.
  • purchase_setup: This method prepares the system for a purchase by verifying payment details without actually charging the customer. For example, a customer adds items to their cart and proceeds to checkout. Before finalizing the purchase, the system runs purchase_setup to confirm all payment details, but no funds are transferred until the customer confirms the order.
  • authorize_setup: This method prepares the system for an authorization-only transaction. This process holds the necessary funds but does not transfer them, ensuring that the customer has sufficient balance for the transaction. It sets up the conditions for a future capture of the authorized funds. For example, a customer places a pre-order for a product that will ship in two weeks. The merchant uses authorize_setup to prepare for the payment authorization. This holds the customer's funds to ensure they can cover the purchase but waits to capture the payment until the product ships. This ensures that payment is secured but not collected prematurely.
note

Split payments can be performed using any methods for any gateway.

  • You can partially pay funds using purchase method. The gateway attempts to charge the customer immediately, and the payment status for an order will show partially_paid
  • You can partially pay for an order using authorize method where the order will be marked as partially_authorized. The transaction must be completed for the order status to be partially_authorized.
  • A purchase_setup method allows verification of payment details for partial payments without transferring funds until the customer confirms the full order.
  • An authorize_setup method can be used to hold a partial amount of the total funds, ensuring the customer has enough balance for a future capture. Until a payment is made neither purchase_setup nor authorize_setup affects the payment statuses, and the order remains unpaid. For more information about order and payment statuses for split payments, see Split payments.

Request​

Path Parameters

    orderID stringrequired

    The Universally Unique Identifier (UUID) of the order you want to pay for.

Body

    data object
    oneOf
    gateway stringrequired

    Possible values: [adyen]

    Specifies the gateway. You must use adyen.

    method stringrequired

    Possible values: [authorize, purchase, purchase_setup, authorize_setup]

    Specifies the transaction method, such as purchase or authorize.

    amount number

    The amount to be paid for the transaction.

    options object
    shopper_reference string

    The shopper reference token associated with the saved payment method.

    recurring_processing_model string

    Enter CardOnFile for a one-time purchase.

    payment stringrequired

    The Adyen recurringDetailReference payment method identifier.

Responses​

OK

Schema
    data object
    id uuid

    The ID of the transaction.

    reference string

    The payment gateway reference.

    name string

    A custom name associated with the payment method.

    custom_reference string

    A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.

    gateway string

    Possible values: [adyen, authorize_net, braintree, card_connect, cyber_source, elastic_path_payments_stripe, manual, paypal_express_checkout, stripe, stripe_connect, stripe_payment_intents]

    The name of the payment gateway used.

    amount number

    The amount for this transaction.

    refunded_amount number

    The refunded amount.

    currency string

    The transaction currency.

    transaction-type string

    The type of transaction, such as purchase, capture, authorize or refund.

    status string

    The status provided by the gateway for this transaction, such as complete or failed.

    relationships object
    order object
    data object
    type string

    Represents the type of the object being returned. It is always order.

    id uuid

    The ID of the order.

    meta object
    display_price object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    display_refunded_amount object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    timestamps object
    created_at string

    The date this was created.

    updated_at

    The date this was last updated.

Loading...