Skip to main content
API docs by Redocly

Pay iO API (1.42.4)

Download OpenAPI specification:Download

Payment

Get the list of available banks

If the merchant is in test/sandbox mode, only return sandbox banks.
Need Merchant API Key

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the list of available banks for merchants

If the merchant is in test/sandbox mode, only return sandbox banks.
Need API Key

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get bank details

No Authentication needed

Authorizations:
api_key
path Parameters
institutionId
required
string

Bank Id provided by Yapily

Responses

Response samples

Content type
application/json
{
  • "countries": [
    ],
  • "credentialsType": { },
  • "environmentType": { },
  • "features": [
    ],
  • "fullName": "string",
  • "id": "string",
  • "media": [
    ],
  • "name": "string"
}

Create a payment authorisation

Get Payment authorisation from Yapily and get the authorisation URL and QRCode URL for the client to authorise the payment with their bank.
Need Merchant API Key

Authorizations:
api_key
Request Body schema: application/json
institutionId
required
string

Bank ID provided by Yapily

cartId
required
string

Merchant reference for the purchase. Usually called cartID

Responses

Request samples

Content type
application/json
{
  • "institutionId": "natwest-sandbox",
  • "cartId": "user-cart-c0e9b438cc104be1a448d63fe8f318dc"
}

Response samples

Callback route once the client has authorised the payment

Only to be used as a callback from Yapily

Responses

Get the Payment Status

Need a Merchant API Key

Authorizations:
api_key
query Parameters
tracingId
required
string
Example: tracingId=c0e9b438cc104be1a448d63fe8f318dc

payment tracing ID, provided by Yapily, sent to gateway with the callback

Responses

Response samples

Content type
application/json
{
  • "merchantName": "string",
  • "paymentStatus": {
    }
}

Get if a transaction has been paid or not

Need a Merchant API Key

Authorizations:
api_key
query Parameters
cartId
required
string
Example: cartId=c0e9b438cc104be1a448d63fe8f318dc

cartId for the transaction of this merchant

Responses

Transactions

Get a transaction

Get a transaction based on the merchant reference and merchant API key.
** Require Merchant API Key **

Authorizations:
api_key
path Parameters
cartId
required
string

Responses

Response samples

Content type
application/json
{
  • "queryData": "string",
  • "id": "string",
  • "merchantId": "string",
  • "clientId": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "cartTax": 0,
  • "totalAmount": 0,
  • "totalTax": 0,
  • "lineItems": [
    ],
  • "shippingType": "string",
  • "shippingMethods": [
    ],
  • "status": "string",
  • "merchantReference": "string",
  • "currency": "string",
  • "paymentReference": "string",
  • "paymentAuthorisationInfo": "string",
  • "tracingId": "string",
  • "paymentId": "string",
  • "consentToken": "string",
  • "statusHistory": "string",
  • "refundAmount": 0,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "paymentSuccessUrl": "string",
  • "checkoutUrl": "string",
  • "secureToken": "string",
  • "publicOrderReference": "string",
  • "pendingCount": 0,
  • "statusDetails": "string",
  • "refundReference": "string",
  • "charges": 0,
  • "yapilyPaymentRequest": "string",
  • "sandbox": true,
  • "digitalOnly": true,
  • "institutionId": "string"
}

Create a transaction. Recreate the transaction with the new data if already exists

Authorizations:
api_key
Request Body schema: application/json
cartId
required
string

Internal reference from your e-commerce platform.
Used to uniquely identify this transaction.

totalAmount
required
object

Total amount to be paid. Can be a number or a String representing a number
Include total cart value, taxes, and shipping value

required
Array of objects (CartItem)

List of Items in the customer cart

currency
string

Currency code for the payment

publicOrderReference
string

Reference number visible by the customer.
If not provided the cartId will be used

secureToken
string

token to be used by the API to update the payment status on the e-commerce site.
This ensure only the API can update the status of only this transaction

paymentSuccessUrl
required
string

URL to redirect user after successful payment.

checkoutUrl
required
string

URL to redirect user to the checkout page if payment fails.

digitalOnly
object

Whether or not this transaction only has digital items. This will mean customers don't need to specify a shipping address

customerEmail
required
string
customerFirstName
string
customerLastName
string

Responses

Request samples

Content type
application/json
{
  • "cartId": "wc_cart_12345678ab",
  • "totalAmount": "28.95",
  • "lineItems": [
    ],
  • "currency": "GBP",
  • "publicOrderReference": "Order 25",
  • "secureToken": "string",
  • "paymentSuccessUrl": "https://my-shop.co.uk/success?order=12345678ab",
  • "checkoutUrl": "https://my-shop.co.uk/checkout",
  • "digitalOnly": { },
  • "customerEmail": "string",
  • "customerFirstName": "string",
  • "customerLastName": "string"
}

Response samples

Content type
application/json
{
  • "queryData": "string",
  • "gatewayUrl": "string",
  • "transaction": { }
}

Update a transaction

Authorizations:
api_key
Request Body schema: application/json
cartId
required
string

Internal reference from your e-commerce platform.
Used to uniquely identify this transaction.

totalAmount
required
object

Total amount to be paid. Can be a number or a String representing a number
Include total cart value, taxes, and shipping value

required
Array of objects (CartItem)

List of Items in the customer cart

currency
string

Currency code for the payment

publicOrderReference
string

Reference number visible by the customer.
If not provided the cartId will be used

secureToken
string

token to be used by the API to update the payment status on the e-commerce site.
This ensure only the API can update the status of only this transaction

paymentSuccessUrl
required
string

URL to redirect user after successful payment.

checkoutUrl
required
string

URL to redirect user to the checkout page if payment fails.

digitalOnly
object

Whether or not this transaction only has digital items. This will mean customers don't need to specify a shipping address

customerEmail
string
customerFirstName
string
customerLastName
string

Responses

Request samples

Content type
application/json
{
  • "cartId": "wc_cart_12345678ab",
  • "totalAmount": "28.95",
  • "lineItems": [
    ],
  • "currency": "GBP",
  • "publicOrderReference": "Order 25",
  • "secureToken": "string",
  • "paymentSuccessUrl": "https://my-shop.co.uk/success?order=12345678ab",
  • "checkoutUrl": "https://my-shop.co.uk/checkout",
  • "digitalOnly": { },
  • "customerEmail": "string",
  • "customerFirstName": "string",
  • "customerLastName": "string"
}

Response samples

Content type
application/json
{
  • "queryData": "string",
  • "gatewayUrl": "string",
  • "transaction": { }
}

Update the client details of a Transaction

Authorizations:
api_key
Request Body schema: application/json
cartId
required
string
customerEmail
required
string
customerFirstName
required
string
customerLastName
required
string

Responses

Request samples

Content type
application/json
{
  • "cartId": "string",
  • "customerEmail": "string",
  • "customerFirstName": "string",
  • "customerLastName": "string"
}

Response samples

Content type
application/json
{ }

Merchants

Get the merchant details using the Merchant API Key

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{ }

Save the merchant settings

Authorizations:
api_key
Request Body schema: application/json
sandboxed
boolean <"true", "false", "yes", "no", "0", "1", true or false>

Set if the PayIO API should be used on test/sandbox mode or not

logoUrl
string

Logo file URL

logoText
string

Alt text for the logo

buttonMainColor
string <Hexadecimal with leading #>

PayIo button color

pluginActive
boolean <boolean>

whether the merchant plugin has been activated or not

platformBackendBaseUrl
string

Base path of the backend of your platform. Needed to be able to send payment status update for supported platforms

paymentStatusUpdateUrl
string

Full path URL to update the payment status to your platform. Needed for the custom API integration

shippingCalculationCallback
string

Full path URL to get the shipping information from the e-commerce platform. Needed for the custom API integration

Responses

Request samples

Content type
application/json
{
  • "sandboxed": "true",
  • "logoUrl": "string",
  • "logoText": "Brand Name Logo",
  • "buttonMainColor": "#fc6603",
  • "pluginActive": "true",
  • "platformBackendBaseUrl": "string",
  • "paymentStatusUpdateUrl": "string",
  • "shippingCalculationCallback": "string"
}

Response samples

Content type
application/json
{
  • "sandboxed": true,
  • "logo": "string",
  • "logoText": "string",
  • "buttonMainColor": "string",
  • "pluginActive": true,
  • "paymentStatusUpdateUrl": "string",
  • "platformBackendBaseUrl": "string",
  • "shippingCalculationCallback": "string"
}