Adding the payment source

How to add a Axerve payment source to an order

Problem

You have a pending order with a selected payment method that is associated with an Axerve payment integration. You want to give your customer the possibility to select Axerve to process the payment.

Solution

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

Adding a payment source

Example

1. Get the payment source type

Request

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

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

Response

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

{
  "data": {
    "id": "jNbQLhMeqo",
    "type": "orders",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/orders/jNbQLhMeqo"
    },
    "attributes": {...},
    "relationships": {
      "market": {
        "links": {...
        }
      },
      "customer": {
        "links": {...
        }
      },
      "shipping_address": {
        "links": {...
        }
      },
      "billing_address": {
        "links": {...
        }
      },
      "payment_method": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/orders/jNbQLhMeqo/relationships/payment_method",
          "related": "https://yourdomain.commercelayer.io/api/orders/jNbQLhMeqo/payment_method"
        },
        "data": {
          "type": "payment_methods",
          "id": "PNMGGzsQMd"
        }
      },
      "payment_source": {
        "links": {...
        }
      },
      "line_items": {
        "links": {...
        }
      },
      "shipments": {
        "links": {...
        }
      },
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
    {
      "id": "PNMGGzsQMd",
      "type": "payment_methods",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/payment_methods/PNMGGzsQMd"
      },
      "attributes": {
        "payment_source_type": "axerve_payments",
        "name": "Axerve 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": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...
          }
        },
        "payment_gateway": {
          "links": {...
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ]
}

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

Request

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

curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/axerve_payments' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \  
  -d '{
  "data": {
    "type": "axerve_payments",
    "attributes": {
      "return_url": "https://checkout.yourdomain.com/jNbQLhMeqo/axerve"
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "jNbQLhMeqo"
        }
      }
    }
  }
}'

Response

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

{
  "data": {
    "id": "ZaDVpIqzeq",
    "type": "axerve_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/axerve_payments/ZaDVpIqzeq"
    },
    "attributes": {
      "return_url": "https://checkout.yourdomain.com/jNbQLhMeqo/axerve",
      "payment_request_data": {
        "paymentID": "1223321",
        "paymentToken": "Asjdlfad5543AA33a",
        "userRedirect":{"href":""},
        "intent_amount_cents":2000
      },
      "mismatched_amounts": false,
      "intent_amount_cents": 2000,
      "intent_amount_float" :20.0,
      "formatted_intent_amount": "€20,00",
      "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/axerve_payments/ZaDVpIqzeq/relationships/order",
          "related": "https://yourdomain.commercelayer.io/api/axerve_payments/ZaDVpIqzeq/order"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Additional notes

Client-side payment approval

The successful Axerve payment creation returns all the pieces of information you need to get the payment approval in the Axerve client-side integration flow, such as the paymentID and the paymentToken — see Axerve documentation for any reference.

Payment source nullification

Axerve payments are synchronous. When a Commerce Layer's axerve_payment is created and associated with an order, Axerve immediately creates a payment intent using the current order's total_amount as the amount to be authorized. If the order is modified before placement its amount and the original intent amount may differ, resulting in an error. To prevent that scenario previously created Axerve's payment sources are nullified in case of order edit/refresh (or if the payment method associated with the order is changed) and must be recreated.

In view of this, make sure to set the payment source as the last step of your checkout implementation.

Axerve Lightbox performs the whole payment workflow within an iframe. Make sure to place the order once you've got a response on your client, otherwise the authorization will not succeed.

More to read

See our documentation if you need more information on how to retrieve an order, include associations, or create an Axerve payment.