This method is called when the Point of Sale (cash register / terminal) wishes to start a reservation (The customer does not have to be checked-in in advance). ReservationStart is only possible if no active MobilePay reservation entity exists for current PoS. A ReservationStart will delete an earlier finished reservation entity – if it is in status ‘Done’, ‘Cancel’ or ‘Error’. It is expected that the PoS system keeps track of reservations internally in order to be able to capture them late
{
"MerchantId":"POSDK99999",
"LocationId":"88888",
"PoSId":"a123456-b123-c123-d123-e12345678901",
"OrderId":"123A124321",
"Amount":"1023.43",
"BulkRef":"MP Bulk Reference",
"CaptureType”:”Full"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| MerchantId | String | required | Id of the merchant. |
| LocationId | String | required | Location ID related to current merchant ID and PoS ID. |
| PoSId | String | required | Current Point of Sale ID (cash register/terminal). |
| OrderId | String | required | Order ID that identifies the payment to refund. |
| Amount | String | required | Amount to refund. If 0.00 or blank, the whole transaction will be refunded. Note: Decimal point is “.” Examples: "Amount": "0.00" - "Amount": "100.00" |
| BulkRef | String | required | Note: this parameter is required but currently only a placeholder for future use. For now, passed values will not be used, but we recommend preparing your solution for this feature. We expect to implement this in an upcoming update of the API. An option for grouping the refunds – a text or ID. The field has a maximum length of 18 characters. If the field remains empty and the merchant does not have a Bulkpost agreement, the merchant will receive all mobile refunds from any connected shops as individual postings in the reconciliation file. If the field remains empty and the merchant does have a Bulkpost agreement, the merchant will receive all mobile refunds bulked with a default BulkRef of the MP Enterprise Serialnumber value in the reconciliation file. It must be a merchant decision whether they want all individual postings or an bulk posting per store or the entire group as one posting. |
| CaptureType | String | required | Full = Fixed to always capture full (initial) amount when ReservationCapture is called Partial = Amounts equal to or lower than initial amount sent with ReservationStart is accepted |
HTTP 200 – Ok
{
"CustomerToken":null,
}
| Parameter | Type | Description |
|---|---|---|
| CustomerToken | String | Contains loyalty card number, if user is part of a loyalty program with the current Merchant, and has enrolled a loyalty card with MobilePay, the loyalty card Null if not part of loyalty program. |
HTTP 400 – See ReservationStart error codes
{
"StatusCode":10,
"StatusText":"Missing or invalid parameters"
}
| Error code | Error text | 10 | Missing or invalid parameters. | </tr>
|---|---|
| 30 | The key “MerchantId, LocationId and PoSId” does not exist |
| 40 | Reservation already exists and has been accepted. |
| 50 | Reservation already in progress. |
Get a Reservation status for current PoS ID. Used for polling for status. Polling has to be done every 1 second until the ReservationStatus is 100 (‘Done’) or if the reservation request has been rejected (ReservationStatus 40 (‘Cancel’) or 50 (‘Error’)).
{
"MerchantId":"POSDK99999",
"LocationId":"88888",
"PoSId":"a123456-b123-c123-d123-e12345678901",
"OrderId":"123A124321"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| MerchantId | String | required | Id of the merchant. |
| LocationId | String | required | Location ID related to current merchant ID and PoS ID. |
| PoSId | String | required | Current Point of Sale ID (cash register/terminal). |
| OrderId | String | required | Order ID related to current reservation status request. |
HTTP 200 – Ok
{
"PoSId":"a123456-b123-c123-d123-e12345678901",
"ReservationStatus":100,
"OrderId":"123A124321",
"Amount":1023.43,
"CustomerId":" B52456-9123-A153-D923-721345678901",
"CustomerToken":"",
}
| Parameter | Type | Description |
|---|---|---|
| PoSId | String | Unique ID that identifies the PoS that has initiated current reservation request. |
| PaymentStatus | Integer | See status values below - 10 ('Idle') No reservation request in the queue - 20 ('Issued') - reservation request is sent to customer. - 30 ('AwaitCheckIn') - Await customer check-in. - 40 ('Cancel') - Customer has cancelled/rejected reservation request. - 50 ('Error') - MobilePay is not able to handle the reservation – the PoS should cancel the MobilePay reservation request. - 80 ('ReservationAccepted') - The reservation request is accepted by the customer – await reservation confirmation from the reservation transaction system. - 100 ('Done') - "reservation Confirmed" and TransactionId, PaymentSignature, Amount, CustomerId (optional) will contain a value. |
| OrderId | String | The OrderId assigned to current reservation . |
| TransactionId | String | Unique ID that identifies the payment (transaction ID). ID is generated by MobilePay and is shown on the receipt inside the MobilePay app. |
| Amount | Number | The amount for the reservation. Note: Decimal point is “.” |
| CustomerId | String | Unique ID of the customer. The ID is generated by MobilePay. |
| CustomerToken | String | Contains customer token if customer has checked-In with a merchant token ID related to this merchant’s loyalty program. |
| CustomerReceiptToken | String | Used for customer receipt token (In DK: Service agreement with Storebox implies that Storebox user Id is provided) Max 32 char. |
| PaymentSignature | null | null (deprecated). |
HTTP 400 – See GetReservationStatus error codes
{
"StatusCode":10,
"StatusText":"Missing or invalid parameters"
}
| Error code | Error text | 10 | Missing or invalid parameters. | </tr>
|---|---|
| 30 | The key “MerchantId, LocationId and PoSId” does not exist |
Cancel Reservation request for current PoS ID. Cancel is principal possible as long as earlier request for reservation hasn’t been finalized. A ReservationCancel will delete current reservation entity active or not unless earlier finished reservation ended in status Done (status code 100) which will remains until a new reservation starts.
{
"MerchantId":"POSDK99999",
"LocationId":"88888",
"PoSId":"a123456-b123-c123-d123-e12345678901",
"OrderId":"123A124321"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| MerchantId | String | required | Id of the merchant. |
| LocationId | String | required | Location ID related to current merchant ID and PoS ID. |
| PoSId | String | required | Current Point of Sale ID (cash register/terminal). |
| OrderId | String | required | Order ID related to current reservation |
HTTP 200 – Ok
{
}
HTTP 400 – See ReservationCancel error codes
{
"StatusCode":10,
"StatusText":"Missing or invalid parameters"
}
| Error code | Error text | 10 | Missing or invalid parameters. | </tr>
|---|---|
| 30 | The key “MerchantId, LocationId and PoSId” does not exist |
| 50 | Action not possible. |
Get Information about the current reservation.
{
"MerchantId":"POSDK99999",
"LocationId":"88888",
"PoSId":"a123456-b123-c123-d123-e12345678901"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| MerchantId | String | required | Id of the merchant. |
| LocationId | String | required | Location ID related to current merchant ID and PoS ID. |
| PoSId | String | required | Current Point of Sale ID (cash register/terminal). |
HTTP 200 – Ok
{
"PosId": " a123456-b123-c123-d123-e12345678901",
"PosUnitId": "123456789012345",
"PaymentStatus": 50,
"OrderId": "123A124321",
"TransactionId": null,
"Amount": 0.01,
"CustomerId": " B52456-9123-A153-D923-721345678901",
"CustomerToken": null,
"CustomerReceiptToken": null,
"LastestUpdate": "2017-05-22T10:00:02.977"
}
HTTP 400 – See GetCurrentReservation error codes
{
"StatusCode":10,
"StatusText":"Missing or invalid parameters"
}
This method is called when the Point of Sale (cash register / terminal) wishes to Capture the Reservation ReservationCapture is only possible when a Reservation exists with the provided order ID. Reservations made as Full Capture reservations should always be captured with 0.00 in amount, and Partial Capture with the amount to capture
{
"MerchantId":"POSDK99999",
"LocationId":"88888",
"PoSId":"a123456-b123-c123-d123-e12345678901",
"OrderId":"123A124321",
"Amount":"1023.43",
"BulkRef":"MP Bulk Reference"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| MerchantId | String | required | Id of the merchant. |
| LocationId | String | required | Location ID related to current merchant ID and PoS ID. |
| PoSId | String | required | Current Point of Sale ID (cash register/terminal). |
| OrderId | String | required | The OrderId is a unique id that identifies the payment. The OrderId is issued by the merchant and is attached to the reservation inside MobilePay system. The order ID must be unique for the merchant/location combination. This means that there should be only one completed reservation with any given order ID for the same merchant and location (store) during the lifetime of the merchant/location. CASE SENSITIVE |
| Amount | String | required | The amount for the payment. Always with 2 decimals and no thousand separators. For capture of reservations made with CaptureType = Full – amount is to be set to 0.00 Note: Decimal point is "." |
| BulkRef | String | required | An option for grouping the payments – a text or ID. The field has a maximum length of 18 characters. If the field remains empty and the merchant does not have a Bulkpost agreement, the merchant will receive all mobile payments from any connected shops as individual postings in the reconciliation file. If the field remains empty and the merchant does have a Bulkpost agreement, the merchant will receive all mobile payments bulked with a default bulkref of the MP Enterprise Serialnumber value in the reconciliation file. It must be a merchant decision whether they want all individual postings or a bulk posting per store or the entire group as one posting. The field is mandatory in the request even though it might be an empty string. |
HTTP 200 – Ok
{
}
HTTP 400 – See ReservationCapture error codes
{
"StatusCode":10,
"StatusText":"Missing or invalid parameters"
}
| Error code | Error text | 10 | Missing or invalid parameters. | </tr>
|---|---|
| 30 | The key “MerchantId, LocationId and PoSId” does not exist |
| 50 | Error during card capture process. |