NAV
curl Node.JS Python

DMBPay v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

Authentication

Payments Integration.

Payments Requests.

Create a new payment request.

Code samples

# You can also use wget
curl -X POST https://api.dmbpay.com/v1/request-payment \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.dmbpay.com/v1/request-payment', headers = headers)

print(r.json())

POST /v1/request-payment

Obtain a payment redirect URL.

Body parameter

{
  "amount": "1999",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "basket_items": [
    {
      "description": "string",
      "quantity": "10",
      "price": "199",
      "total": "1990"
    }
  ],
  "country_code": "GB",
  "currency": "GBP",
  "description": "Payment for Order Number #325682",
  "failed_url": "https://example.org/failed",
  "first_payment_date": "20/03/2020",
  "frequency": "daily",
  "number_of_payments": 0,
  "payment_type": "PERIODIC",
  "parent_payment_id": 0,
  "reference_id": "string",
  "redirect_url": "https://example.org/success",
  "options": "{\"sessionId\":\"foo\"}"
}

Parameters

Name In Type Required Description
body body RequestPaymentSchema false Makes request for payment redirect URL.

Example responses

200 Response

{
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  },
  "payment_request_id": "123456",
  "redirect_url": "https://pay.vendreo.com/payment/{uuid}",
  "subscription_id": "123456"
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.
» payment_request_id string false none none
» redirect_url string false none none
» subscription_id string false none none

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Card Payments Integration.

Create a new card payment request.

Code samples

# You can also use wget
curl -X POST https://api.dmbpay.com/v1/card/request-payment \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.dmbpay.com/v1/card/request-payment', headers = headers)

print(r.json())

POST /v1/card/request-payment

Obtain a payment token to be used with the Card JS SDK.

Body parameter

{
  "amount": "1999",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "country_code": "GB",
  "currency": "GBP",
  "customer_name": "Joe Blogs",
  "customer_billing_email": "Joe Blogs",
  "customer_billing_address": "123 Foo Street",
  "customer_billing_town": "London",
  "customer_billing_post_code": "GB",
  "customer_billing_country_code": "AA1 1AA",
  "tokenize_payment": "true",
  "enable_address_field": "true",
  "disable_auto_capture": "true",
  "enable_verify_card": "true",
  "mandate_3ds_challenge": "true",
  "ip_address": "1.12.123.255",
  "user_session_id": "b5a3aa9b-7583-4434-8e69-1253453c99de",
  "description": "Payment for Order Number #325682",
  "reference_id": "string",
  "options": "{\"sessionId\":\"foo\"}"
}

Parameters

Name In Type Required Description
body body CardRequestPaymentSchema false Creates a token for use on Card JS SDK.

Example responses

200 Response

{
  "payment_request_id": "123456",
  "payment_request_token": "{uuid}",
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» payment_request_id string false none none
» payment_request_token string false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Get details of payment.

Code samples

# You can also use wget
curl -X GET https://api.dmbpay.com/v1/card/payment/{paymentCard}/details \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.dmbpay.com/v1/card/payment/{paymentCard}/details', headers = headers)

print(r.json())

GET /v1/card/payment/{paymentCard}/details

Obtain the most up-to-date details about a payment

Body parameter

{}

Parameters

Name In Type Required Description
paymentCard path string true none
body body CardPaymentDetails false Gets the most up-to-date details about a payment.

Example responses

200 Response

{
  "uuid": "98edad0a-83bd-44f7-8e67-f7db7e9fbc73",
  "payment_type": "PAYMENT",
  "environment": "SANDBOX",
  "transaction_id": "123456789",
  "cross_reference": "A1B2C3D4E5F6G7H8I9J0",
  "type": "E_COMMERCE",
  "action": "SALE",
  "status": "CONFIRMED",
  "state": "ACCEPTED",
  "merchant_account": "12346789",
  "merchant_category_code": "1234",
  "amount": 100,
  "amount_received": 100,
  "amount_retained": 100,
  "payment_method": "card",
  "card_type": "Visa Debit",
  "card_scheme": "Visa",
  "currency_symbol": "£",
  "currency_exponent": "2",
  "last_4": "1234",
  "card_hash": "string",
  "card_issuer": "string",
  "card_expiry": "string",
  "card_issuing_country": "United Kingdom",
  "customer_name": "string",
  "customer_address": "string",
  "customer_postcode": "string",
  "customer_country": "string",
  "customer_email": "string",
  "customer_ip": "string",
  "security_address_check": "matched",
  "security_post_code_check": "matched",
  "security_3d_secure_check": "authenticated",
  "security_risk_check": "Y",
  "security_cvv2_check": "matched",
  "token_uuid": "string",
  "payment_request": {
    "uuid": "98edad0a-83bd-44f7-8e67-f7db7e9fbc73",
    "merchant_id": "string",
    "action": "SALE",
    "amount": 100,
    "type": "1",
    "currency_code": "GBP",
    "country_code": "GBR",
    "customer_name": "string",
    "customer_billing_email": "string",
    "customer_billing_address": "string",
    "customer_billing_post_code": "string",
    "reference": "9485b43b-00d3-4fdd-9ddc-84383afcd067",
    "description": "10 Credits",
    "meta": {}
  },
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» uuid string(uuid) false none none
» payment_type string false none none
» environment string false none none
» transaction_id string false none none
» cross_reference string false none none
» type string false none none
» action string false none none
» status string false none none
» state string false none none
» merchant_account string false none none
» merchant_category_code string false none none
» amount integer false none none
» amount_received integer false none none
» amount_retained integer false none none
» payment_method string false none none
» card_type string false none none
» card_scheme string false none none
» currency_symbol string false none none
» currency_exponent string false none none
» last_4 string false none none
» card_hash string false none Hash of the unique card number, expiry, and CVV.
» card_issuer string false none none
» card_expiry string false none none
» card_issuing_country string false none none
» customer_name string false none none
» customer_address string false none none
» customer_postcode string false none none
» customer_country string false none none
» customer_email string false none none
» customer_ip string false none none
» security_address_check string false none none
» security_post_code_check string false none none
» security_3d_secure_check string false none none
» security_risk_check string false none none
» security_cvv2_check string false none none
» token_uuid string false none none
» payment_request object false none none
»» uuid string(uuid) false none none
»» merchant_id string false none none
»» action string false none none
»» amount integer false none none
»» type string false none none
»» currency_code string false none none
»» country_code string false none none
»» customer_name string false none none
»» customer_billing_email string false none none
»» customer_billing_address string false none none
»» customer_billing_post_code string false none none
»» reference string false none none
»» description string false none none
»» meta object false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Create a refund from an existing payment.

Code samples

# You can also use wget
curl -X DELETE https://api.dmbpay.com/v1/card/payment/{paymentCard}/refund \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.dmbpay.com/v1/card/payment/{paymentCard}/refund', headers = headers)

print(r.json())

DELETE /v1/card/payment/{paymentCard}/refund

Creates a refund payment.

Body parameter

{
  "amount": 0,
  "reason": [
    "DUPLICATE_ORDER",
    "GOODS_RETURNED",
    "ORDER_CANCELLED",
    "MERCHANT_OUT_OF_STOCK",
    "GOODS_NOT_RECEIVED",
    "LATE_CONFIRMATION",
    "DISPUTES"
  ]
}

Parameters

Name In Type Required Description
paymentCard path string true none
body body CardRefundPaymentDetails false Refund a payment.

Example responses

200 Response

{
  "payment": {
    "payment_uuid": "98d9aa80-9632-4602-80f5-2f6ff9f93097",
    "environment": "SANDBOX",
    "amount": 1500,
    "options": [
      "string"
    ],
    "payment_request_uuid": "d91e2cb6-62c0-402d-b8a3-c58d80205b74",
    "payment_request_id": "12345"
  },
  "refund_payment": {
    "refund_uuid": "98f3f009-aca3-4c8f-bd4d-d1c9ff05b5a5",
    "environment": "SANDBOX",
    "amount": 1500
  },
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» payment object false none none
»» payment_uuid string false none none
»» environment string false none none
»» amount number false none none
»» options [string] false none none
»» payment_request_uuid string false none none
»» payment_request_id string false none none
» refund_payment object false none none
»» refund_uuid string false none none
»» environment string false none none
»» amount number false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Stop a pending payment from being processed.

Code samples

# You can also use wget
curl -X DELETE https://api.dmbpay.com/v1/card/payment/{paymentCard}/cancel \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.dmbpay.com/v1/card/payment/{paymentCard}/cancel', headers = headers)

print(r.json())

DELETE /v1/card/payment/{paymentCard}/cancel

You can stop a payment from being processed by cancelling it.

Body parameter

{}

Parameters

Name In Type Required Description
paymentCard path string true none
body body CardCancelPaymentDetails false Allows you to cancel a payment that is being processed.

Example responses

200 Response

{
  "payment_uuid": "98f3ed2b-fca5-48e6-b7d3-a7745be3eeec",
  "amount": 1500,
  "options": [
    "string"
  ],
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» payment_uuid string false none none
» amount number false none none
» options [string] false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Void Transaction.

Code samples

# You can also use wget
curl -X DELETE https://api.dmbpay.com/v1/card/payment/{paymentCard}/void \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.dmbpay.com/v1/card/payment/{paymentCard}/void', headers = headers)

print(r.json())

DELETE /v1/card/payment/{paymentCard}/void

Either cancels or refunds a payment.

Body parameter

{
  "amount": 0,
  "reason": [
    "DUPLICATE_ORDER",
    "GOODS_RETURNED",
    "ORDER_CANCELLED",
    "MERCHANT_OUT_OF_STOCK",
    "GOODS_NOT_RECEIVED",
    "LATE_CONFIRMATION",
    "DISPUTES"
  ]
}

Parameters

Name In Type Required Description
paymentCard path string true none
body body CardVoidPayment false Voids a transaction.

Example responses

200 Response

{
  "type": [
    "REFUND",
    "CANCEL"
  ],
  "payment": {
    "payment_uuid": "b1073176-a151-4923-b545-fa987e333530",
    "environment": "string",
    "amount": 0,
    "options": [],
    "payment_request_uuid": "string",
    "payment_request_id": "string"
  },
  "refund_payment": {
    "refund_uuid": "6a036737-fcc1-4a9b-b03c-3f39d33819b5",
    "environment": "string",
    "amount": 0
  },
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» type string false none Type of refund/cancel.
» payment object false none none
»» payment_uuid string(uuid) false none Payment UUID of the payment
»» environment string false none Environment of the payment
»» amount integer false none Amount of the payment
»» options array false none Amount of the payment
»» payment_request_uuid string false none Reference UUID of the payment request
»» payment_request_id string false none Reference ID of the payment request
» refund_payment object¦null false none none
»» refund_uuid string(uuid) false none Payment UUID of the created refund
»» environment string false none Environment of the refund
»» amount integer false none Amount of the refund
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Enumerated Values

Property Value
type ["REFUND","CANCEL"]

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

View all Ban Entries.

Code samples

# You can also use wget
curl -X GET https://api.dmbpay.com/v1/card/bans \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.dmbpay.com/v1/card/bans', headers = headers)

print(r.json())

GET /v1/card/bans

You can view all Ban Entries.

Body parameter

{}

Parameters

Name In Type Required Description
body body ListBan false Allows you to see what bans are currently active.

Example responses

200 Response

[
  {
    "id": "199",
    "type": "IP_ADDRESS",
    "reference_id": "8.8.8.8",
    "created_at": "2023-08-01 10:10:00"
  }
]

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» anonymous object false none none
»» id string false none none
»» type string false none none
»» reference_id string false none Reference of the ban.
»» expires_at string false none Expiry date of the ban.
»» created_at string false none When the ban was created.
» meta object false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Enumerated Values

Property Value
type ["IP_ADDRESS","CARD_HASH"]

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Banning a Card or IP address.

Code samples

# You can also use wget
curl -X POST https://api.dmbpay.com/v1/card/bans/add \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.dmbpay.com/v1/card/bans/add', headers = headers)

print(r.json())

POST /v1/card/bans/add

You can provide a Card Hash or IP Address to ban.

Body parameter

{
  "type": [
    "IP_ADDRESS",
    "CARD_HASH"
  ],
  "reference": "8.8.8.8",
  "expires_at": "2019-08-24T14:15:22Z"
}

Parameters

Name In Type Required Description
body body AddBan false Allows you to ban an IP address or a card PAN hash.

Example responses

200 Response

{
  "success": "true",
  "ban_id": 1500,
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none
» ban_id number false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Remove a banned Card or IP address.

Code samples

# You can also use wget
curl -X DELETE https://api.dmbpay.com/v1/card/bans/{ban}/remove \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.dmbpay.com/v1/card/bans/{ban}/remove', headers = headers)

print(r.json())

DELETE /v1/card/bans/{ban}/remove

You can remove a banned Card or IP address.

Body parameter

{}

Parameters

Name In Type Required Description
ban path string true none
body body RemoveBan false Allows deletion of a ban.

Example responses

200 Response

{
  "success": "true",
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Capture a payment that has been approved.

Code samples

# You can also use wget
curl -X POST https://api.dmbpay.com/v1/card/payment/{paymentCard}/capture \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.dmbpay.com/v1/card/payment/{paymentCard}/capture', headers = headers)

print(r.json())

POST /v1/card/payment/{paymentCard}/capture

When using the disable auto capture, you will need to manually hit this endpoint to capture the payment.

Body parameter

{
  "amount": 0
}

Parameters

Name In Type Required Description
paymentCard path string true none
body body CardCapturePaymentDetails false Allows you to capture a payment that has been approved.

Example responses

200 Response

{
  "payment_uuid": "98f3ed2b-fca5-48e6-b7d3-a7745be3eeec",
  "amount": 1500,
  "options": [
    "string"
  ],
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» payment_uuid string false none none
» amount number false none none
» options [string] false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Create a new payment from an existing token.

Code samples

# You can also use wget
curl -X POST https://api.dmbpay.com/v1/card/token/{cardPaymentToken}/rebill \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.dmbpay.com/v1/card/token/{cardPaymentToken}/rebill', headers = headers)

print(r.json())

POST /v1/card/token/{cardPaymentToken}/rebill

Obtain a payment token to be used with the Card JS SDK.

Body parameter

{
  "amount": "1999",
  "description": "string",
  "reference_id": "string",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "country_code": "GB",
  "currency": "GBP"
}

Parameters

Name In Type Required Description
cardPaymentToken path string true none
body body CardRebillPaymentDetails false Rebill a tokenized payment.

Example responses

200 Response

{
  "payment_uuid": "98f3a6d3-46b7-4b72-8a99-ca45ba2a70d0",
  "status": "COMPLETED",
  "environment": "SANDBOX",
  "payment_request_id": "15",
  "payment_request_uuid": "98f3a6d3-4381-4317-b465-a8c988f3f3a3",
  "options": [
    "string"
  ],
  "token": "98d9a8d3-556b-48e2-add4-6418ecbcd684",
  "meta": {
    "tracing_id": "6bc181f1-1512-493f-9c1c-81f66e479193"
  }
}

Responses

Status Meaning Description Schema
200 OK Successful response. Inline
401 Unauthorized Validation errors. Inline
422 Unprocessable Entity Validation errors. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» payment_uuid string false none none
» status string false none none
» environment string false none none
» payment_request_id string false none none
» payment_request_uuid string false none none
» options [string] false none none
» token string false none none
» meta object¦null false none none
»» tracing_id string(uuid) false none Tracing ID to allow support to track down issues.

Status Code 401

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Status Code 422

Name Type Required Restrictions Description
» errors object false none none
»» additionalProperties [string] false none none
» message string false none none

Schemas

CardPaymentDetails

{}

Properties

None

CardRequestPaymentSchema

{
  "amount": "1999",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "country_code": "GB",
  "currency": "GBP",
  "customer_name": "Joe Blogs",
  "customer_billing_email": "Joe Blogs",
  "customer_billing_address": "123 Foo Street",
  "customer_billing_town": "London",
  "customer_billing_post_code": "GB",
  "customer_billing_country_code": "AA1 1AA",
  "tokenize_payment": "true",
  "enable_address_field": "true",
  "disable_auto_capture": "true",
  "enable_verify_card": "true",
  "mandate_3ds_challenge": "true",
  "ip_address": "1.12.123.255",
  "user_session_id": "b5a3aa9b-7583-4434-8e69-1253453c99de",
  "description": "Payment for Order Number #325682",
  "reference_id": "string",
  "options": "{\"sessionId\":\"foo\"}"
}

Properties

Name Type Required Restrictions Description
amount integer true none Amount in pence you wish to charge eg £19.99 would be represented as 1999.
application_key string(uuid) true none Your Payment Profile Application API Key.
country_code string true none The country code of the transaction eg GB.
currency string true none The currency of the transaction eg GBP.
customer_name string false none The name of the customer.
customer_billing_email string false none The name of the customer (If empty, card form will display this field).
customer_billing_address string false none The billing address of the customer (If empty, card form will display this field).
customer_billing_town string false none The billing town of the customer (If empty, card form will display this field).
customer_billing_post_code string false none The billing postcode of the customer (If empty, card form will display this field).
customer_billing_country_code string false none The billing country code of the customer (If empty, card form will display this field).
tokenize_payment boolean¦null false none Tokenize card payment details for re-billing
enable_address_field boolean¦null false none Require the customer to provide an address
disable_auto_capture boolean¦null false none Disable auto capturing payments - payment needs to be manually confirmed before processing.
enable_verify_card boolean¦null false none Ensure a card is valid and active without charging the card (Amount field must be 0 when this field is active)
mandate_3ds_challenge boolean¦null false none Disables frictionless 3D secure payments
ip_address string¦null false none IP v4 address of client making the transaction using dotted decimal notation (eg. 1.12.123.255). This should be provided where possible to aid fraud prevention.
user_session_id string¦null false none Provide a user session ID which will link payment requests together - this should be provided where possible to aid fraud prevention. Note: hosted versions will automatically get this feature so should be left empty.
description string true none A short description of the payment.
reference_id string true none Your internal reference for the transaction.
options string¦null false none none

CardRefundPaymentDetails

{
  "amount": 0,
  "reason": [
    "DUPLICATE_ORDER",
    "GOODS_RETURNED",
    "ORDER_CANCELLED",
    "MERCHANT_OUT_OF_STOCK",
    "GOODS_NOT_RECEIVED",
    "LATE_CONFIRMATION",
    "DISPUTES"
  ]
}

Properties

Name Type Required Restrictions Description
amount integer¦null false none Amount you want to refund.
reason string true none Reason for refunding the payment.

Enumerated Values

Property Value
reason ["DUPLICATE_ORDER","GOODS_RETURNED","ORDER_CANCELLED","MERCHANT_OUT_OF_STOCK","GOODS_NOT_RECEIVED","LATE_CONFIRMATION","DISPUTES"]

CardCancelPaymentDetails

{}

Properties

None

CardRebillPaymentDetails

{
  "amount": "1999",
  "description": "string",
  "reference_id": "string",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "country_code": "GB",
  "currency": "GBP"
}

Properties

Name Type Required Restrictions Description
amount integer true none Amount in pence you wish to charge eg £19.99 would be represented as 1999.
description string true none Description of the payment.
reference_id string true none Your internal reference for the transaction.
application_key string(uuid) true none Your Payment Profile Application API Key.
country_code string true none The country code of the transaction eg GB.
currency string true none The currency of the transaction eg GBP.

AddBan

{
  "type": [
    "IP_ADDRESS",
    "CARD_HASH"
  ],
  "reference": "8.8.8.8",
  "expires_at": "2019-08-24T14:15:22Z"
}

Properties

Name Type Required Restrictions Description
type string true none Type of ban, for example (IP or card hash).
reference string true none Reference of the ban (Card Hash or IP).
expires_at string(date-time)¦null false none Expiry date of the ban.

Enumerated Values

Property Value
type ["IP_ADDRESS","CARD_HASH"]

RemoveBan

{}

Properties

None

ListBan

{}

Properties

None

CardVoidPayment

{
  "amount": 0,
  "reason": [
    "DUPLICATE_ORDER",
    "GOODS_RETURNED",
    "ORDER_CANCELLED",
    "MERCHANT_OUT_OF_STOCK",
    "GOODS_NOT_RECEIVED",
    "LATE_CONFIRMATION",
    "DISPUTES"
  ]
}

Properties

Name Type Required Restrictions Description
amount integer¦null false none Amount you want to refund.
reason string true none Reason for refunding the payment.

Enumerated Values

Property Value
reason ["DUPLICATE_ORDER","GOODS_RETURNED","ORDER_CANCELLED","MERCHANT_OUT_OF_STOCK","GOODS_NOT_RECEIVED","LATE_CONFIRMATION","DISPUTES"]

CardCapturePaymentDetails

{
  "amount": 0
}

Properties

Name Type Required Restrictions Description
amount integer¦null false none Amount you want to capture (leave empty if you want to capture the original amount).

AISDefaultSchema

{}

Properties

None

AISTransactionSchema

{
  "date_from": "2022-01-01",
  "date_to": "2022-01-30",
  "page": 1
}

Properties

Name Type Required Restrictions Description
date_from string¦null false none Retrieve transactions with a date on or after this date.
date_to string¦null false none Retrieve transactions with a date on or before this date.
page integer¦null false none Which page of the paginated results to return.

AISAuthorizationSchema

{
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "cancel_url": "https://example.org/failed",
  "country_code": "GB",
  "description": "Payment for Order Number #325682",
  "reference_id": "string",
  "redirect_url": "https://example.org/success",
  "options": "{\"sessionId\":\"foo\"}"
}

Properties

Name Type Required Restrictions Description
application_key string(uuid) true none Your Payment Profile Application API Key.
cancel_url string true none Where the user will be redirect upon failure.
country_code string true none The country code of the transaction eg GB.
description string false none A short description of the payment.
reference_id string true none Your internal reference for the transaction.
redirect_url string true none Where the user will be redirect upon success.
options string¦null false none none

CreateSubscriptionSchema

{
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "country_code": "GB",
  "currency": "GBP",
  "description": "Payment for Order Number #325682",
  "first_amount": "1999",
  "frequency": "daily",
  "number_of_payments": 0,
  "recurring_amount": "1999",
  "redirect_url": "https://example.org/success",
  "reference_id": "string",
  "options": "{\"sessionId\":\"foo\"}"
}

Properties

Name Type Required Restrictions Description
application_key string(uuid) true none Your Payment Profile Application API Key.
country_code string false none The country code of the transaction eg GB.
currency string true none The currency of the transaction eg GBP.
description string true none A short description of the payment.
first_amount integer true none Initial amount in pence you wish to charge eg £19.99 would be represented as 1999.
frequency string false none The recurring payment frequency following the initial payment. Note this is only used if payment_type is PERIODIC.
number_of_payments integer false none Number of payments expected. Note this is only used with Periodic Payments.
recurring_amount integer true none Recurring amount in pence you wish to charge eg £19.99 would be represented as 1999.
redirect_url string true none Where the user will be redirect upon success.
reference_id string true none Your internal reference for the transaction.
options string¦null false none none

Enumerated Values

Property Value
frequency daily
frequency monthly
frequency weekly

RequestPaymentSchema

{
  "amount": "1999",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "basket_items": [
    {
      "description": "string",
      "quantity": "10",
      "price": "199",
      "total": "1990"
    }
  ],
  "country_code": "GB",
  "currency": "GBP",
  "description": "Payment for Order Number #325682",
  "failed_url": "https://example.org/failed",
  "first_payment_date": "20/03/2020",
  "frequency": "daily",
  "number_of_payments": 0,
  "payment_type": "PERIODIC",
  "parent_payment_id": 0,
  "reference_id": "string",
  "redirect_url": "https://example.org/success",
  "options": "{\"sessionId\":\"foo\"}"
}

Properties

Name Type Required Restrictions Description
amount integer true none Amount in pence you wish to charge eg £19.99 would be represented as 1999.
application_key string(uuid) true none Your Payment Profile Application API Key.
basket_items [object]¦null false none Used to provide the user a description of the basket contents on the payment summary screen.
» description string false none Description of the line item.
» quantity integer false none Quantity of the line item.
» price string false none Price per line item.
» total string false none Total price for the line item.
country_code string false none The country code of the transaction eg GB.
currency string true none The currency of the transaction eg GBP.
description string true none A short description of the payment.
failed_url string false none Where the user will be redirect upon failure.
first_payment_date string false none Initial charge date.
frequency string false none The recurring payment frequency following the initial payment. Note this is only used if payment_type is PERIODIC.
number_of_payments integer false none Number of payments expected. Note this is only used with Periodic Payments.
payment_type string true none The type of payment.
parent_payment_id integer¦null false none none
reference_id string true none Your internal reference for the transaction.
redirect_url string true none Where the user will be redirect upon success.
options string¦null false none none

Enumerated Values

Property Value
frequency daily
frequency monthly
frequency weekly
payment_type PERIODIC
payment_type SINGLE
payment_type CARD

RequestAPaymentSchema

{
  "amount": "1999",
  "currency": "GBP",
  "description": "Payment for Order Number #325682",
  "redirect_url": "https://example.org/success",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05"
}

Properties

Name Type Required Restrictions Description
amount integer true none Amount in pence you wish to charge eg £19.99 would be represented as 1999.
currency string true none The currency of the transaction eg GBP.
description string true none A short description of the payment.
redirect_url string true none Where the user will be redirect upon success.
application_key string(uuid) true none Your Payment Profile Application API Key.

RequestOutgoingPaymentSchema

{
  "account_name": "Mr Joe Bloggs",
  "account_number": "12345678",
  "amount": "1999",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05",
  "currency": "GBP",
  "description": "Payment for Order Number #325682",
  "options": "{\"sessionId\":\"foo\"}",
  "original_payment_uuid": "c012a5cc-5435-4935-b8f3-b022f2605df8",
  "redirect_url": "https://example.org/success",
  "sort_code": "123456"
}

Properties

Name Type Required Restrictions Description
account_name string¦null false none The receiving bank account owner name.
account_number string¦null false none The receiving bank account number.
amount integer true none Amount in pence you wish to send eg £19.99 would be represented as 1999.
application_key string(uuid) true none Your Payment Profile Application API Key.
currency string true none The currency of the transaction eg GBP.
description string true none A short description of the payment.
options string¦null false none none
original_payment_uuid string(uuid)¦null false none none
redirect_url string true none Where the user will be redirect upon success.
sort_code string¦null false none The receiving bank account sort code.

PaymentsSchema

{
  "payments": [
    "c012a5cc-5435-4935-b8f3-b022f2605df8"
  ]
}

Properties

Name Type Required Restrictions Description
payments [string]¦null true none The payment uuids that you wish to retrieve.

PaymentSchema

{}

Properties

None

HeadlessSetupSchema

{
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05"
}

Properties

Name Type Required Restrictions Description
application_key string(uuid) true none Your Payment Profile Application API Key.

HeadlessRequestPaymentSchema

{
  "amount": "1999",
  "basket_items": [
    {
      "description": "string",
      "quantity": "10",
      "price": "199",
      "total": "1990"
    }
  ],
  "country_code": "GB",
  "currency": "GBP",
  "description": "Payment for Order Number #325682",
  "failed_url": "https://example.org/failed",
  "first_payment_date": "20/03/2020",
  "frequency": "daily",
  "payment_type": "PERIODIC",
  "parent_payment_id": 0,
  "redirect_url": "https://example.org/success",
  "reference_id": "string",
  "remote_institution_id": "barclays",
  "number_of_payments": 0,
  "options": "{\"sessionId\":\"foo\"}",
  "application_key": "19899181-5f37-4282-90d1-683e69cf3d05"
}

Properties

Name Type Required Restrictions Description
amount integer true none Amount in pence you wish to charge eg £19.99 would be represented as 1999.
basket_items [object]¦null false none Used to provide the user a description of the basket contents on the payment summary screen.
» description string false none Description of the line item.
» quantity integer false none Quantity of the line item.
» price string false none Price per line item.
» total string false none Total price for the line item.
country_code string false none The country code of the transaction eg GB.
currency string true none The currency of the transaction eg GBP.
description string true none A short description of the payment.
failed_url string false none Where the user will be redirect upon failure.
first_payment_date string false none Initial charge date.
frequency string false none The recurring payment frequency following the initial payment. Note this is only used if payment_type is PERIODIC.
payment_type string true none The type of payment.
parent_payment_id integer¦null false none none
redirect_url string true none Where the user will be redirect upon success.
reference_id string true none Your internal reference for the transaction.
remote_institution_id string false none The users selected institution id.
number_of_payments integer false none Number of payments expected. Note this is only used with Periodic Payments.
options string¦null false none none
application_key string(uuid) true none Your Payment Profile Application API Key.

Enumerated Values

Property Value
frequency daily
frequency monthly
frequency weekly
payment_type PERIODIC
payment_type SINGLE
curl Node.JS Python