Adding the payment source

How to add an external payment source to an order

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.

pageAdding a payment source

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

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