Making a payment

In order to make a payment, follow the steps below:

  1. Create an order by using the POST method on the ORDER resource.
  2. You can update the order, for example to update the shopping cart or the commission fee amounts.
  3. Fix the order to make the payment using the GET method:
    • Either on the URL of the execute attribute provided in the ORDER links, in this case the response contains the redirection URL (payment_url attribute).
    • Or on the URL of the execute-embedded attribute for initializing payment via embedded form, in this case the response contains a formToken (form_token attribute).
  4. Redirect the Buyer to the URL of the payment page or display the embedded form using the form token.

Step 1

In order to declare items in your order, you must mention the ?expand=items argument in the URL (/marketplace/orders?expand=items).

Otherwise, your items will not be taken into account (the list of items returned by the server is empty) and the order will be created without items. When the order is executed (step 3), you encounter the error 400 {"amount":"The sum of item amounts cannot be zero or negative."}.

Example of a POST ORDER call:

POST https://secure.lyra.com/marketplace/orders?expand=items
{
  "marketplace": "ebfb36ab-2d30-4326-adb9-e16b0c9a89f3",
  "reference": "MKP BURO example",
  "description": "Office supplies order",
  "currency": "EUR",
  "url_return": "https://URLreturn.com",
"items": [
    {
      "seller": "d0f80202-0676-4d8d-9247-f455f30aec1b",
      "reference": "commburo",
      "description": "commission BURO",
      "amount": 150,
      "is_commission": true
    },
    {
      "seller": "5d0ef88c-3345-4b33-948e-80e23d553b73",
      "reference": "STB1",
      "description": "Blue pens”,
      "amount": 1000,
      "is_commission": false
    }
  ],
  "buyer": {
    "type": "PRIVATE",
    "email": "john.smith@buyer.com",
    "phone_number": "33 (0)1 11 22 33 44",
    "reference": "ZhIsYM"
  },
  "shipping": {
    "shipping_method": "RELAY_POINT"
  }
}

Example of a POST ORDER response :
{
  "uuid": "1a2b51f8-9d62-408f-ab39-aa8e28ab15f0",
  "href": "https://secure.lyra.com/marketplace/orders/1a2b51f8-9d62-408f-ab39-aa8e28ab15f0",
"created_at": "2019-01-21T16:46:46.517000Z",
  "updated_at": "2019-01-21T16:46:46.517000Z",
  "marketplace": "ebfb36ab-2d30-4326-adb9-e16b0c9a89f3",
  "reference": "MKP BURO example",
  "description": "Office supplies order",
  "alias": null,
  "buyer": [
    {
      "reference": "ZhIsYM",
      "title": null,
      "type": "PRIVATE",
      "first_name": null,
      "last_name": null,
      "legal_name": null,
      "phone_number": "33 (0)1 11 22 33 44",
      "email": "john.smith@buyer.com",
      "address": null
    }
  ],
  "shipping": [
    {
      "shipping_method": "RELAY_POINT",
      "delivery_company_name": null,
      "shipping_speed": null,
      "shipping_delay": null,
      "type": null,
      "first_name": null,
      "last_name": null,
      "legal_name": null,
      "phone_number": null,
      "address": null
    }
  ],
  "amount": null,
  "initial_amount": null,
  "currency": "EUR",
  "status": "CREATED",
  "webhook_result": null,
  "url_return": "https://URLreturn.com",
"items": [
    {
      "uuid": "d33ba1ab-793e-4d3d-943f-72b14a1e885b",
      "href": "https://secure.lyra.com/marketplace/items/d33ba1ab-793e-4d3d-943f-72b14a1e885b",
"created_at": "2019-01-21T16:46:46.510000Z",
      "updated_at": "2019-01-21T16:46:46.573000Z",
      "seller": "5d0ef88c-3345-4b33-948e-80e23d553b73",
      "order": "1a2b51f8-9d62-408f-ab39-aa8e28ab15f0",
      "reference": "STB1",
      "description": "Blue pens”,
      "type": "ENTERTAINMENT",
      "amount": 1000,
      "quantity": 1,
      "transfer": null,
      "status": "CREATED",
      "links": null,
      "is_commission": false
    },
    {
      "uuid": "20034374-b425-4beb-91a8-a660ca5a3f9b",
      "href": "https://secure.lyra.com/marketplace/items/20034374-b425-4beb-91a8-a660ca5a3f9b",
"created_at": "2019-01-21T16:46:46.502000Z",
      "updated_at": "2019-01-21T16:46:46.551000Z",
      "seller": "d0f80202-0676-4d8d-9247-f455f30aec1b",
      "order": "1a2b51f8-9d62-408f-ab39-aa8e28ab15f0",
      "reference": "commburo",
      "description": "commission BURO",
      "type": "ENTERTAINMENT",
      "amount": 150,
      "quantity": 1,
      "transfer": null,
      "status": "CREATED",
      "links": null,
      "is_commission": true
    }
  ],
  "links": {
    "items": {
    "href": "https://secure.lyra.com/marketplace/orders/1a2b51f8-9d62-408f-ab39-aa8e28ab15f0/items"
    },
    "refunds": {
    "href": "https://secure.lyra.com/marketplace/orders/1a2b51f8-9d62-408f-ab39-aa8e28ab15f0/refunds"
    },
    "execute": {
    "href": "https://secure.lyra.com/marketplace/orders/1a2b51f8-9d62-408f-ab39-aa8e28ab15f0/execute"
    },
    "execute-embedded": {
    "href": "https://secure.lyra.com/marketplace/orders/1a2b51f8-9d62-408f-ab39-aa8e28ab15f0/execute-embedded"
    }
  },
  "vads_transaction_id": 0,
  "vads_transaction_date": null,
  "expected_capture_date": null,
  "capture_delay": null
}

Step 2

An order can be updated (multiple times) via the PUT ORDER query (/marketplace/orders/<order_uuid>?expand=items) using the order_uuid returned in step 1.

The buyer and shipping attributes must be specified.

The item list is updated with each PUT. If you wish to add another item, you must transmit it with the already created items. Otherwise, the list will only contain one item.

On the other hand, in order to remove an item, you need to return a complete list of items without the item that you wish to remove.

Example of a PUT ORDER call for adding an item to the cart:

PUT https://secure.lyra.com/marketplace/orders/515abac9-6cb2-4e21-8a25-b08d7e41e43c?expand=items

{
  "marketplace": "ebfb36ab-2d30-4326-adb9-e16b0c9a89f3",
  "reference": "MKP BURO example",
  "description": "Office supplies order",
  "currency": "EUR",
  "url_return": "https://URLreturn.com",
"items": [
    {
      "seller": "d0f80202-0676-4d8d-9247-f455f30aec1b",
      "reference": "commburo",
      "description": "commission BURO",
      "amount": 270,
      "is_commission": true
    },
    {
      "seller": "5d0ef88c-3345-4b33-948e-80e23d553b73",
      "reference": "STB1",
      "description": "Blue pens”,
      "amount": 1000,
      "is_commission": false
    },
    {
    "seller": "5d0ef88c-3345-4b33-948e-80e23d553b73",
    "reference": "STR3",
    "description": "Red pens",
    "amount": 1000,
    "is_commission": false
    },
  ],
  "buyer": {
    "type": "PRIVATE",
    "email": "john.smith@buyer.com",
    "phone_number": "33 (0)1 11 22 33 44",
    "reference": "ZhIsYM"
  },
  "shipping": {
    "shipping_method": "RELAY_POINT"
  }
}

Step 3

With the exception of manually validated payments (see chapter Manual validation payment), before making the execution request and freezing the order, you must make sure that the commission amount is higher than the required minimum. If this is not the case, the execution request will return a validation error 400 with the message {"commission": "Insufficient amount of commission."}.

You can find information on the minimum commission in the Commission principle section of the chapter Presentation of the Marketplace.

Example of a GET call via redirection for freezing the order:

GET
https://secure.lyra.com/marketplace/orders/515abac9-6cb2-4e21-8a25-b08d7e41e43c/execute

Example of a GET response:

{
	'payment_url': 'https://secure.lyra.com/vads-payment/exec.refresh.a;jsessionid=HqKAcpvcgZQA29qCZDjXw4kS.marketplacevad01?cacheId=450272311503195000050'
}						

Example of a GET call via the embedded form for freezing the order:

GET https://secure.lyra.com/marketplace/orders/515abac9-6cb2-4e21-8a25b08d7e41e43c/execute-embedded

Example of a GET response:
{"form_token":"fa0yfV2FQuR3aak1SwsgcuZg195eyJhbW91bnQiOjEwOTAwLCJjdXJyZW5jeSI6IkVVUiIsIm
							1vZGUiOiJURVNUIiwidmVyc2lvbiI6Mywib3JkZXJJZCI6IjVjNDk1N2E5LWNkOGEtNGJhZC1hMGNiLTgxMT
							ZiMWE3ZDdmNiIsInNob3BOYW1lIjoiTHlyYSBTTVMiLCJicmFuZFByaW9yaXR5IjpbIkJBTkNPTlRBQ1QiL
							CJDQiIsIkUtQ0FSVEVCTEVVRSIsIk1BU1RFUkNBUkQiLCVGQVVMVCJ9fX0a702"}

Note: the size of the form_token can be up to 8KB.

Step 4

In the case of payment with redirection, simply redirect the Buyer to the provided link. The same address can be used for an iframe display.

In case of an embedded payment form, the form_token must be inserted in the form (kr-form-token attribute).

Example:

<body> 
	<!-- payment form --> 
	<div class="kr-embedded"
	kr-form-token="fa0yfV2FQuR3aak1SwsgcuZg195eyJhbW91bnQiOjEwOTAwLCJjdXJyZW5jeSI6IkVVUiIsIm
			1vZGUiOiJURVNUIiwidmVyc2lvbiI6Mywib3JkZXJJZCI6IjVjNDk1N2E5LWNkOGEtNGJhZC1hMGNiLTgxMT
			ZiMWE3ZDdmNiIsInNob3BOYW1lIjoiTHlyYSBTTVMiLCJicmFuZFByaW9yaXR5IjpbIkJBTkNPTlRBQ1QiL
			CJDQiIsIkUtQ0FSVEVCTEVVRSIsIk1BU1RFUkNBUkQiLCVGQVVMVCJ9fX0a702">
 	<!-- payment form fields -->
		<div class="kr-pan"></div>
		<div class="kr-expiry"></div>
		<div class="kr-security-code"></div>

		<!-- payment form submit button -->
		<button class="kr-payment-button"></button>
		<!-- error zone --> 
		<div class="kr-form-error"></div> 
	</div> 
</body>