WebSockets API to connect to MultiPay APM.
| Parameter | Type | Description |
|---|---|---|
| Authorization | Header | Oauth2 bearer token obtained from authorization endpoint |
| X-Terminal-Id | Header | This is a unique terminal identifier |
Production URL's will be provided after successful integration in test environment
If an expected (or unexpected) error occurs, a problem will be sent to the client with a description and a "mappable" type.
| Type | Example description | Example use case |
|---|---|---|
| apm.mtm.input-error | PaymentReceiptId must be a numeric value | Returned when a refund is initiated with a non-numeric receiptId |
| apm.mtm.merchant-validation-error | Merchant with id: xxx is not configured correctly in MultiPay | Returned when there is something wrong with the merchant setup in MultiPay |
| apm.mtm.payment-not-found | Payment was not found by receiptId: 123456789 | Returned when a refund is initiated, but not found in MultiPay |
| apm.mtm.payment-already-refunded | Payment already refunded | Returned when a payment is already refunded |
| apm.mtm.unexpected-error | Failed to cancel payment with id: 123456789 towards MultiPay APM API | Something unexpected happens, i.e no response from MultiPay |
Public server that requires authorization.
Example of how to fetch a token to use with this API (client_id and client_secret will be provided by us).
curl -X POST "https://apm.dev.payex.com/authorization/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=XXXX" \
--data-urlencode "client_secret=XXXX" \
--data-urlencode "scope=terminal"
JWT token used to identify processing entity
JWT token used to identify processing entity
Send messages to the API
Available only on servers:
Accepts one of the following messages:
This is sent from client to server when a "POST-flow" is initiated
{
"id": "a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"messageType": "PAYMENT_INIT_REQUEST",
"paymentDetails": {
"description": "Payment by Terminal simulator",
"currencyIso": "NOK",
"paymentExpireDateTime": "2023-01-01T00:00:00+01:00",
"totalAmount": 13.37,
"vatRate": 25,
"products": []
},
"merchant": {
"id": "63f601ba-46c8-4c77-9b3d-17b235488ef6",
"poiId": "123456",
"name": "Terminal simulator"
},
"customerOrderId": "6afdd46f-c117-4c05-92ef-dc37e1aba062",
"saleTransactionId": "2cbd4b9e-67e0-4bff-9a32-d7ac6084382f"
}
This can be sent from server to client if a end-used decides to abort payment. It can also be sent from client to server to indicate the payment was aborted in terminal
{
"id": "a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"messageType": "STATUS_UPDATE",
"state": "CANCELED",
"reason": ""
}
This is sent from client to server to initiate a refund. It will result in a "PAYMENT_RECEIPT" response sent from server til client when refund is completed.
{
"paymentReceiptId": "12345678910",
"totalAmount": 100,
"merchant": {
"id": "63f601ba-46c8-4c77-9b3d-17b235488ef6",
"poiId": "123456",
"name": "Terminal simulator"
}
}
Messages that you receive from the API
Available only on servers:
Accepts one of the following messages:
This is returned to client when a successful logon/subscribe is done
{
"messageType": "LOGON_CONFIRMATION",
"paymentLink": "https://stage-evc.payex.com/multipay-apm-api/instore-payment/id/"
}
This is sent from server to client when a "GET-flow" is initiated
{
"id": "a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"messageType": "GET_PAYMENT_REQUEST"
}
This is sent from server to client as a response to PAYMENT_INIT_REQUEST
{
"id": "a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"customerOrderId": "6afdd46f-c117-4c05-92ef-dc37e1aba062",
"saleTransactionId": "2cbd4b9e-67e0-4bff-9a32-d7ac6084382f",
"state": "PENDING",
"paymentLink": "https://stage-evc.payex.com/multipay-apm-api/instore-payment/id/a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"messageType": "PAYMENT_INIT_RESPONSE"
}
This can be sent from server to client if a end-used decides to abort payment. It can also be sent from client to server to indicate the payment was aborted in terminal
{
"id": "a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"messageType": "STATUS_UPDATE",
"state": "CANCELED",
"reason": ""
}
This is sent from server to client when a payment has been completed
{
"id": "a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"customerOrderId": "6afdd46f-c117-4c05-92ef-dc37e1aba062",
"saleTransactionId": "2cbd4b9e-67e0-4bff-9a32-d7ac6084382f",
"paymentReceiptId": 12345678910,
"terminalId": "andr3",
"state": "COMPLETE",
"paymentDetails": {
"totalAmount": 100,
"totalVatAmount": 20,
"products": [],
"currencyIso": "NOK",
"description": "Payment by Terminal simulator",
"vatRate": 25,
"paymentExpireDateTime": "2023-01-01T00:00:00+01:00"
},
"customerDetails": {
"msisdn": "+4700000000"
},
"merchant": {
"id": "63f601ba-46c8-4c77-9b3d-17b235488ef6",
"poiId": "123456",
"name": "Terminal simulator"
},
"processorId": "VAS_ECR",
"selectedPaymentInstrument": "VIPPS",
"maskedInstrument": "908xxx42",
"paymentLink": "https://stage-evc.payex.com/multipay-apm-api/instore-payment/id/a6a74ffe-1b82-4cff-ba6f-0fd34848d76a",
"messageType": "PAYMENT_RECEIPT"
}
This is sent from server to client when a unexpected problem occurs
{
"messageType": "PROBLEM",
"reason": "Failed to process message: {xxxx}",
"type": "apm.mtm.payment-not-found"
}
This is returned to client when a successful logon/subscribe is done
This is sent from server to client when a "GET-flow" is initiated
This is sent from server to client as a response to PAYMENT_INIT_REQUEST
This is sent from client to server when a "POST-flow" is initiated
This can be sent from server to client if a end-used decides to abort payment. It can also be sent from client to server to indicate the payment was aborted in terminal
This is sent from server to client when a payment has been completed
This is sent from client to server to initiate a refund. It will result in a "PAYMENT_RECEIPT" response sent from server til client when refund is completed.
This is sent from server to client when a unexpected problem occurs
Payment details
Optional array of products
Merchant information
Unique identifier for payment request
Link to active payment
Currency ISO string (3-letter code) ISO_4217
Payment state
Customer information
TODO:: Denne må beskrives med noe fornuftig
TODO:: Denne må beskrives med noe fornuftig