Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Example
  • Additional notes
  • More to read
  1. Placing orders
  2. Payments
  3. External payments

Adding the payment source

How to add an external payment source to an order

PreviousExternal paymentsNextReusing the payment source

Last updated 2 years ago

Problem

You have a pending order with a selected payment method that is associated with an external payment gateway. You want to give your customer the possibility to process the payment using the external endpoint you configured.

Solution

To add an external payment source to an order, you have to create an external payment source object and associate it with the order, as described in the Checkout guide.

Example

1. Get the payment source type

The following request retrieves the attributes of the payment method associated with the order identified by the "qaMAhZkZvd" ID:

curl -g -X GET \
  'http://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd?include=payment_method' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

On success, the API responds with a 200 OK status code, returning the requested order object and the associated payment method:

{
  "data": {
    "id": "qaMAhZkZvd",
    "type": "orders",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd"
    },
    "attributes": {...},
    "relationships": {
      "market": {
        "links": {...}
      },
      "customer": {
        "links": {...}
      },
      "shipping_address": {
        "links": {...}
      },
      "billing_address": {
        "links": {...}
      },
      "available_payment_methods": {
        "links": {...}
      },
      "available_payment_methods": {
        "links": {...}
      },
      "payment_method": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd/relationships/payment_method",
          "related": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd/payment_method"
        },
        "data": {
          "type": "payment_methods",
          "id": "GmvVesqPmj"
        }
      },
      "payment_source": {
        "links": {...}
      },
      "line_items": {
        "links": {...}
      },
      "shipments": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
    {
      "id": "GmvVesqPmj",
      "type": "payment_methods",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/payment_methods/GmvVesqPmj"
      },
      "attributes": {
        "payment_source_type": "external_payments",
        "name": "External Payment",
        "disabled_at": null,
        "price_amount_cents": 0,
        "price_amount_float": 0.0,
        "formatted_price_amount": "€0,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "",
        "reference_origin": "",
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...}
        },
        "payment_gateway": {
          "market": {
            "links": {...}
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ]
}

2. Create the payment source and associate it with the order

The following request creates an external payment object and associates it with the order identified by the "qaMAhZkZvd" ID:

curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/external_payments' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "external_payments",
    "attributes": {
      "payment_source_token": "xxxx.yyyy.zzzz"      
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "qaMAhZkZvd"
        }
      }
    }
  }
}'

On success, the API responds with a 201 Created status code, returning the created external payment object:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "external_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/external_payments/xYZkjABcde"
    },
    "attributes": {
      "payment_source_token": "xxxx.yyyy.zzzz",
      "options": null,
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/external_payments/xYZkjABcde/relationships/order",
          "related": "https://yourdomain.commercelayer.io/api/external_payments/xYZkjABcde/order"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Additional notes

Asynchronous payments

More to read

Commerce Layer provides the option to mark your external payments as asynchronous. See our for more information.

See our documentation if you need more information on how to , , or . See our Checkout guide for more details on how to place an order.

Adding a payment source
official documentation
retrieve an order
include associations
create an external payment
Placing the order