Authorization
Whenever you want to charge the customer using a customer token you need to create an authorization which can be auto captured, or captured at a later stage.
Creating an authorization​
The customer token created previously can be used to charge the customer at any time. The customer is charged by creating an authorization using the customer token.
- Request
- Response
- Error
POST /purchase/authorizations HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json
{
"customerToken": "f590b7c4-0d2e-4d99-a3c7-5c1a39f45dce",
"storeId": "1234",
"order": {
"items":[
{
"id": "id-001",
"description": "Description 002",
"unitPrice": "10",
"quantity": "1",
"vat": "25"
},
{
"id": "id-002",
"description": "Description 002",
"unitPrice": "2",
"quantity": "10",
"vat": "12"
}
],
"currency": "EUR",
"reference": "01478520",
"actionReference": "reference 1234",
"captureMode": "Auto"
},
"attemptSchedule": {
"relative": ["00:00:10", "00:00:10", "00:00:10", "00:00:10", "1.00:00:10"],
"absolute": ["2023-12-24T14:00:00", "2023-12-11T18:30:00"],
"preferSynchronous": true
}
}
If the request is accepted for processing, a response with HTTP status code 202 Accepted
is returned. If the authorization could be performed synchronously, the response will contain the authorization id and order id with HTTP status code 200 OK
.
HttpStatusCode: 202 Accepted
{
"id": "17635160-e66f-46b9-84fc-db939005050c",
"data": {
"authorizationId": "f874e54d-2d58-4d31-a769-857dc3972979"
}
}
HttpStatusCode: 200 OK
{
"id": "17635160-e66f-46b9-84fc-db939005050c",
"data": {
"authorizationId": "f874e54d-2d58-4d31-a769-857dc3972979",
"orderId": "f874e54d-2d58-4d31-a769-857dc3972979"
}
}
// Example error. More errors available below.
HttpStatusCode: 404 Not Found
{
"id": "fe8a21bb-6cb5-4d7d-b7f6-c0c335fc4593",
"error": {
"code": 404,
"message": "The resource requested was not found.",
"errors": []
}
}
HttpStatusCode: 422 Unprocessable Entity
{
"id": "fe8a21bb-6cb5-4d7d-b7f6-c0c335fc4593",
"error": {
"code": 422,
"message": "The request was rejected by the server due to a business error.",
"errors": [
{
"reason": "PENDING_ACTIVATION",
"message": "The customer token is pending for activation"
}
]
}
}
Request Properties​
Request headers
Header | Required | Explanation |
---|---|---|
Authorization | Yes | Instructions on how to generate the authorization header value can be found here. |
Walley-Idempotency-Key | No | Instructions on how to use idempotency can be found here. |
- Root request properties
- Order
- Items
- Attempt Schedule
Property | Required | Explanation |
---|---|---|
customerToken | Yes | The customer token retrieved from the initial Walley Checkout information |
storeId | No | If not provided then the store id in the customer token is used |
order | Yes | Order related information, see order tab |
attemptSchedule | No | If not provided, we will perform one asynchronous attempt as soon as possible |
Property | Required | Explanation |
---|---|---|
items | Yes | The article id or equivalent. Max 50 characters. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt. |
currency | Yes | The currency for the items in the cart. This must match the currency for the initial transaction |
reference | No | A reference to the order, i.e. order ID or similar. It has a 50-character limit. |
actionReference | No | A reference to this specific action. This will appear as a data property on the settlement report. Maximum 255 characters. |
captureMode | No | CaptureMode can be Auto or Manual. If not specified, it uses the same mode as the initial transaction. Auto means the order gets captured right away after successful authorization. With Manual, you need to manually capture by calling Capture Order. |
Property | Required | Explanation |
---|---|---|
id | Yes | The article id or equivalent. Max 50 characters. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt. |
description | Yes | Descriptions longer than 50 characters will be truncated. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt. |
unitPrice | Yes | The unit price of the article including VAT. Both positive and negative values allowed. Max 2 decimals, i.e. 100.00 |
quantity | Yes | The quantity of the article. Allowed values are 1 to 99999999 . |
vat | Yes | The VAT of the article in percent. Allowed values are 0 to 100 . Max 2 decimals, i.e. 25.00 |
Property | Required | Explanation |
---|---|---|
relative | No * | Timespans in the format of dd.HH:mm:ss , for example 1.00:00:10 . Each attempt is relative to the previous |
absolute | No * | Date and Time information in the ISO 8601 format yyyy-MM-ddTHH:mm:ss±hh:mm , for example 2023-12-11T18:30:00+01:00 . Each attempt is absolute |
preferSynchronous | No * | If set to true , a single attempt will be performed synchronously if no challenge is needed. |
* You can at most set one of relative, absolute or preferSynchronous. |
Important status codes​
Http status code | Cause |
---|---|
200 | Authorization completed synchronously |
202 | Authorization created - asynchronous workflow initiated |
400 | Could be missing required properties, invalid schedule, or other client side verifiable errors |
401 | Incorrect, missing or expired bearer token |
404 | The customer token was not found for the authenticated bearer token |
422 | The synchronous authorization could not be performed |
503 | There was some internal error. Please try again |
General error codes​
Error reason | Cause |
---|---|
INVALID_CURRENCY | The provided currency does not match the currency associated with the customer token. |
TOKEN_PENDING | The customer token is pending review. An authorized signatory must approve or deny the buyer in MyWalley Business |
TOKEN_DENIED | The customer token has been denied. The buyer was denied in MyWalley Business |
TOKEN_REVOKED | The customer token has been revoked. The buyer was revoked in MyWalley Business |
TOKEN_CANCELLED | The customer token has been cancelled using the cancellation endpoint |
UNEXPECTED_ERROR | An unexpected error occurred. Contact Walley support for further investigation. |
IDEMPOTENCY_... | An error related to idempotency. Details can be found in the idempotency section. |
Synchronous-only error codes​
Error reason | Cause |
---|---|
PAYMENT_DENIED | User was denied to purchase with credit |
PAYMENT_FAILED | Payment failed due to technical or configuration issues. Retry the request or contact Walley support. |
ORDER_CREATION_TIMEOUT | Internal timeout occurred while creating the order. Retry using the same idempotency key. |