Create And Manage Payments
Payments API lets developers to create and manage payments. It is important to remember, that payment cannot be completed without user interaction, meaning that user has to swipe and approve payments inside MobilePay app.
Create Payment
The first step in your journey of collecting payments would be to initiate a new payment. You can do that using the following request.
curl https://api.mobilepay.dk/v1/payments \
-X POST \
-H 'x-ibm-client-id: {CLIENT_ID}' \
-H 'Authorization: Bearer {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"amount": 1250,
"idempotencyKey": "{UUID}",
"paymentPointId": "{PAYMENT_POINT_ID}",
"redirectUri": "{URI_TO_YOUR_APP}"
"reference": "{YOUR_UNIQUE_KEY}",
"description": "Details on the product/service that the customer is buying"
}'
{
"paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
"mobilePayAppRedirectUri": "mobilepay://merchant_payments?payment_id=186d2b31-ff25-4414-9fd1-bfe9807fa8b7"
}
tip
mobilePayAppRedirectUri
should be used to redirect user to MobilePay app.
tip
Use description
to inform your customers to a greater extent. Description will be shown on the payment confirmation screen in MobilePay so the customer has more information about the product. The description will also be shown when the MobilePay user opens their payment receipt in the activity list.
tip
We suggest setting unique order or transaction id from your own system in the reference
field. The reference
field will be contained throughout the backend flow of the payment. Also in settlement reports in the MobilePay portal or from our Transaction Reporting API. End-users/customers will see the reference
field value in the receipt of the payment, found in MobilePay app's activity tab.
Get Single Payment Details
Whenever there is a need you can retrieve details of a single payment and e.g. check the current state.
curl https://api.mobilepay.dk/v1/payments/{PAYMENT_ID} \
-X GET \
-H 'x-ibm-client-id: {CLIENT_ID}' \
-H 'Authorization: Bearer {API_KEY}'
{
"paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
"amount": 1250,
"description": "Lorem ipsum",
"paymentPointId": "7347ba06-95c5-4181-82e5-7c7a23609a0e",
"reference": "DFX101103518",
"redirectUri": "https://yourredirecturi",
"state": "initiated",
"initiatedOn": "2021-08-20T05:18:07Z",
"lastUpdatedOn": "2021-08-21T08:45:32Z",
"merchantId": "655ad36f-70b0-4add-a123-b943daca50e8",
"isoCurrencyCode": "DKK",
"paymentPointName": "Nullam tincidunt"
}
Property state
can have these values:
- initiated - initial state.
- reserved - MobilePay user approved payment, ready to be captured.
- captured - final state, funds will be transferred during next settlement.
- cancelledByMerchant - payment was cancelled by you.
- cancelledBySystem - no user interactions with payment were made in 5-10 minutes after creation, so our automated job cancelled it.
- cancelledByUser - user cancelled payment inside MobilePay app.
Get All Payments
Theres also a possibility to list all your payments in pages. Multiple searching criteria can be used as query parameters.
curl https://api.mobilepay.dk/v1/payments \
-X GET \
-H 'x-ibm-client-id: {CLIENT_ID}' \
-H 'Authorization: Bearer {API_KEY}'
{
"pageSize": 1,
"nextPageNumber": 2,
"payments": [
{
"paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
"amount": 1250,
"description": "Lorem ipsum",
"paymentPointId": "7347ba06-95c5-4181-82e5-7c7a23609a0e",
"reference": "DFX101103518",
"redirectUri": "https://yourredirecturi",
"state": "initiated",
"initiatedOn": "2021-08-20T05:18:07Z",
"lastUpdatedOn": "2021-08-21T08:45:32Z",
"merchantId": "655ad36f-70b0-4add-a123-b943daca50e8",
"isoCurrencyCode": "DKK",
"paymentPointName": "Nullam tincidunt"
}
]
}
Capture Payment
After you receive a notification that payment was reserved or you retrieve a payment and it has a state reserved
, you must capture payment in order to end the flow and receive the money with nightly transfer.
note
- Partial capture availability is limited. Let us know your use case during onboarding, and we will let you know if it's available.
- Reservations are canceled after 7 days.
At this point you have 2 options:
- You can capture the whole reserved amount.
- You can do a partial capture and only capture the amount you need. Remaining amount will be returned to the user.
curl https://api.mobilepay.dk/v1/payments/{PAYMENT_ID}/capture \
-X POST \
-H 'x-ibm-client-id: {CLIENT_ID}' \
-H 'Authorization: Bearer {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"amount": 1250
}'
Cancel Payment
If you changed your mind and want to cancel payment , you can do that using the following request.
curl https://api.mobilepay.dk/v1/payments/{PAYMENT_ID}/cancel \
-X POST \
-H 'x-ibm-client-id: {CLIENT_ID}' \
-H 'Authorization: Bearer {API_KEY}' \
Keep in mind, that payment can be cancelled in all states except captured
. If you've already captured payment, refunding is your only option.
If you cancel a reserved payment, reserved amount will be returned to the user.
Cancel Payment By Idempotency Key
You can also cancel payment by sending us the same idempotency key that you've used in the create payment request.
Use this endpoint when the outcome of create payment request is unknown (e.g. network/server error occured and you didn't get a response). It allows to cancel only those payments that are in initiated
state. For all other scenarios, please use the endpoint above.
After successful cancellation, you can create a new payment again.
curl https://api.mobilepay.dk/v1/payments/cancel \
-X POST \
-H 'x-ibm-client-id: {CLIENT_ID}' \
-H 'Authorization: Bearer {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": {UUID}
}'