Introduction

Thanks for using the Pomelo Pay API. It's a great way to build your applications on top of the Pomelo Pay platform.

We've added code bindings for shell scripts, PHP and NodeJS.

This REST API accepts both JSON and Hydra requests (using JSON-LD) to give you as much flexibility as possible.

Please contact us at support@pomelopay.com for any questions you might have regarding this API.

Quick Start

Example request


curl -X GET \
  https://app.pomelopay.com/api/transactions \
  -H 'Authorization: Bearer <apikey>' \
  -H 'Accept: application/json'


<?php 
use PomeloPHP\Client;

$client = new Client('apikey', 'application_id'); // creates a production client
$client = new Client('apikey', 'application_id', 'sandbox'); // creates a sandbox client

To interact with the Pomelo Pay API you need to create a Pomelo Pay application in your merchant portal.

After you create an application we will provide you with a production and sandbox API key and Application ID.

Using the production environment

Make requests to the following base url:

GET https://app.pomelopay.com/api

Using the sandbox environment

Transactions created in our sandbox environment will give you the chance to approve, cancel or error specific transactions.

This will give you the flexibility to create different scenario's for your application.

Make requests to the following base url:

GET https://sandbox.pomelopay.com/api

Required headers

The following headers are available:

Header	Values	Description
Authorization	`Bearer <apikey>`	Your API key generated when you created an application
Accept	`application/json` `application/ld+json`	Receive responses in JSON or JSON-LD format
Content-Type	`application/json`	Specifies the Content-Type of the request body, only JSON is accepted

These headers are usually automatically included if you use any of our Pomelo Pay SDK's.

Authentication

Send your API Key with every request


curl -X GET \
  https://app.pomelopay.com/api/transactions \
  -H 'Authorization: Bearer <apikey>' \
  -H 'Accept: application/json'


<?php 
use PomeloPHP\Client;

$client = new Client('apikey', 'application_id'); // creates a production client
$client = new Client('apikey', 'application_id', 'sandbox'); // creates a sandbox client

To interact with the Pomelo Pay API you need to create a Pomelo Pay application in your merchant portal.

You must send your API key as the Authorization header with every request. Make sure you protect this API key and never share it outside your application.

Some specific requests also require you to send your applicationId.

If you use any of our Pomelo Pay SDK's they will be automatically included if you use the SDK client to make requests.

Make sure you keep your API key and applicationId secure and safe.

Pagination

Example request


curl -X GET \
  https://app.pomelopay.com/api/transactions?page=3&itemsPerPage=10 \
  -H 'Authorization: Bearer <apikey>' \
  -H 'Accept: application/json'

<?php 
use PomeloPHP\Client;

$client = new Client('apikey', 'appid');

$subSet = $client->transactions->all([
  "page" => 3,  // We're on page 3
  "itemsPerPage" => 5 // We're displaying 5 items per page
]);

$all = $client->transactions->all([
  "pagination" => 0 // Don't paginate the results
]);

The Pomelo Pay API offers a flexible pagination structure for GET requests on collections. The following query filters are possible for pagination. The default page number is 1.

Query	Values	Description	Default
pagination	0,1	Disable or enable pagination	1
page	`int`	Page of the collection	1
itemsPerPage	`int`	Numbers of items per page	20

Example to get page 3 of a collection that gives you 10 items per page:

GET https://app.pomelopay.com/api/transactions?page=3&itemsPerPage=10

Example to disable pagination:

GET https://app.pomelopay.com/api/transactions?pagination=0

Transactions

Get all Transactions

Example request


curl -X GET \
  https://app.pomelopay.com/api/transactions \
  -H 'Authorization: Bearer <apikey>' \
  -H 'Accept: application/json'


<?php 
use PomeloPHP\Client;

$client = new Client('apikey', 'application_id'); // creates a production client
$transactions = $client->transactions->all();

Example response

[
    {
        "id": "8d460a24-38ea-11e8-88db-591e8a5a25ac",
        "notes": null,
        "securityWord": "Barbarous Red deer",
        "hashId": "B2yVs1WtNLxuqoEQGO",
        "deviceId": "123456-123456",
        "appVersion": "1.0",
        "provider": "POMELO",
        "history": [
            {
                "state": "CONFIRMED",
                "message": null,
                "displayName": "confirmed",
                "displayNameDescription": "The transaction has been confirmed",
                "created": "2018-04-05T16:01:56+02:00",
                "updated": "2018-04-05T16:01:56+02:00"
            },
            {
                "state": "QR_CODE_GENERATED",
                "message": null,
                "displayName": "pending",
                "displayNameDescription": "The transaction is pending",
                "created": "2018-04-05T16:01:08+02:00",
                "updated": "2018-04-05T16:01:08+02:00"
            },
            {
                "state": "INITIATED",
                "message": null,
                "displayName": "pending",
                "displayNameDescription": "The transaction is pending",
                "created": "2018-04-05T16:01:07+02:00",
                "updated": "2018-04-05T16:01:07+02:00"
            }
        ],
        "qr": {
            "id": "8d9de05a-38ea-11e8-88db-591e8a5a25ac",
            "fileName": "60a9ad0303e5f0634ffc0410c7527e20.png",
            "file": "https://cdn.pomelopay.com/qrcodes/60a9ad0303e5f0634ffc0410c7527e20.png",
        },
        "currentState": "CONFIRMED",
        "currentStateDetails": {
            "state": "CONFIRMED",
            "message": null,
            "displayName": "confirmed",
            "displayNameDescription": "The transaction has been confirmed",
        },
        "providersDetails": {
            "key": "POMELO",
            "displayName": "pomelo",
            "image": "https://s3-eu-west-1.amazonaws.com/pomelodev-shenzhen/providers/icon_pomelo.png"
        },
        "costStructure": {
            "id": "8da3d064-38ea-11e8-88db-591e8a5a25ac",
            "payable": 953,
            "fee": 47,
            "feeRate": 0.022,
            "feeRateExact": 0.047
        },
        "forwardUrl": "http://app.pomelopay.com/hooks/out/8d460a24-38ea-11e8-88db-591e8a5a25ac",
        "redirectUrl": null,
        "meta": null,
        "created": "2018-04-05T16:01:07+02:00",
        "updated": "2018-04-05T16:01:56+02:00",
        "amount": 1000,
        "currency": "GBP"
    },
    ...

This endpoints gets all transactions

HTTP Request

GET https://app.pomelopay.com/api/transactions

Query Parameters

See Pagination

Request body

This request does not accept a body

Response body

Field	Description	Format
id	unique id of the transaction	string
notes	notes added to this transaction	string
securityWord	security word that is added on confirmation	string
hashId	unique hashId of the transaction	string
appVersion	version of the app or API that was used to create this transaction	string
deviceId	id of the device or application that was used to create this transaction	string
provider	the payment provider used for this transaction	string
history	array of transactions states	array
qr	QR code information for this transaction	object
currentState	current state of the transaction	object
costStructure	detailed information about fees and rates	object
forwardUrl	URL to redirect to for payment completion	string
redirectUrl	optional redirect url to go after payment	string
amount	amount in cents for this transactions	int
currency	currency of this transaction	3 letter ISO code
meta	meta information key value format such as email or address	object

Get a specific Transaction

Example request


curl -X GET \
  https://app.pomelopay.com/api/transactions/8d460a24-38ea-11e8-88db-591e8a5a25ac \
  -H 'Authorization: Bearer <apikey>' \
  -H 'Accept: application/json'


<?php 
use PomeloPHP\Client;

$client = new Client('apikey', 'application_id'); // creates a production client
$transactions = $client->transactions->get('8d460a24-38ea-11e8-88db-591e8a5a25ac');

Example response

[
    {
        "id": "8d460a24-38ea-11e8-88db-591e8a5a25ac",
        "notes": null,
        "securityWord": "Barbarous Red deer",
        "hashId": "B2yVs1WtNLxuqoEQGO",
        "deviceId": "123456-123456",
        "appVersion": "1.0",
        "provider": "POMELO",
        "history": [
            {
                "state": "CONFIRMED",
                "message": null,
                "displayName": "confirmed",
                "displayNameDescription": "The transaction has been confirmed",
                "created": "2018-04-05T16:01:56+02:00",
                "updated": "2018-04-05T16:01:56+02:00"
            },
            {
                "state": "QR_CODE_GENERATED",
                "message": null,
                "displayName": "pending",
                "displayNameDescription": "The transaction is pending",
                "created": "2018-04-05T16:01:08+02:00",
                "updated": "2018-04-05T16:01:08+02:00"
            },
            {
                "state": "INITIATED",
                "message": null,
                "displayName": "pending",
                "displayNameDescription": "The transaction is pending",
                "created": "2018-04-05T16:01:07+02:00",
                "updated": "2018-04-05T16:01:07+02:00"
            }
        ],
        "qr": {
            "id": "8d9de05a-38ea-11e8-88db-591e8a5a25ac",
            "fileName": "60a9ad0303e5f0634ffc0410c7527e20.png",
            "file": "https://cdn.pomelopay.com/qrcodes/60a9ad0303e5f0634ffc0410c7527e20.png",
        },
        "currentState": "CONFIRMED",
        "currentStateDetails": {
            "state": "CONFIRMED",
            "message": null,
            "displayName": "confirmed",
            "displayNameDescription": "The transaction has been confirmed",
        },
        "providersDetails": {
            "key": "POMELO",
            "displayName": "pomelo",
            "image": "https://s3-eu-west-1.amazonaws.com/pomelodev-shenzhen/providers/icon_pomelo.png"
        },
        "costStructure": {
            "id": "8da3d064-38ea-11e8-88db-591e8a5a25ac",
            "payable": 953,
            "fee": 47,
            "feeRate": 0.022,
            "feeRateExact": 0.047
        },
        "forwardUrl": "http://app.pomelopay.com/hooks/out/8d460a24-38ea-11e8-88db-591e8a5a25ac",
        "redirectUrl": null,
        "meta": null,
        "created": "2018-04-05T16:01:07+02:00",
        "updated": "2018-04-05T16:01:56+02:00",
        "amount": 1000,
        "currency": "GBP"
    },
    ...

This endpoints gets a specific transaction

HTTP Request

GET https://app.pomelopay.com/api/transactions/:id

Query Parameters

This endpoint does not accept query parameters

Request body

This request does not accept a body

Response body

Field	Description	Format
id	unique id of the transaction	string
notes	notes added to this transaction	string
securityWord	security word that is added on confirmation	string
hashId	unique hashId of the transaction	string
appVersion	version of the app or API that was used to create this transaction	string
deviceId	id of the device or application that was used to create this transaction	string
provider	the payment provider used for this transaction	string
history	array of transactions states	array
qr	QR code information for this transaction	object
currentState	current state of the transaction	object
costStructure	detailed information about fees and rates	object
forwardUrl	URL to redirect to for payment completion	string
redirectUrl	optional redirect url to go after payment	string
amount	amount in cents for this transactions	int
currency	currency of this transaction	3 letter ISO code
meta	meta information key value format such as email or address	object

Create a Transaction

Example request


curl -X POST \
  https://app.pomelopay.com/api/transactions \
  -H 'Authorization: Bearer <apikey>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount" : 1000,
    "provider" : "POMELO",
    "deviceId" : "appid",
    "appVersion": "1.0",
    "currency" : "GBP",
    "redirectUrl" : "https://foo.bar/order/123"
}'


<?php 
use PomeloPHP\Client;

// This will automatically set your API key, deviceId and appVersion in the request
$client = new Client('apikey', 'appid');

$json = [
 "provider" => "POMELO", // Provider enabled for your merchant account such as ALIPAY, ...
 "currency" => "GBP",
 "amount" => 1000, // 10.00 GBP
 "redirectUrl" => "https://foo.bar/order/123" // Optional redirect after payment completion
];

Example response

[
    {
        "id": "8d460a24-38ea-11e8-88db-591e8a5a25ac",
        "notes": null,
        "securityWord": "Barbarous Red deer",
        "hashId": "B2yVs1WtNLxuqoEQGO",
        "deviceId": "123456-123456",
        "appVersion": "1.0",
        "provider": "POMELO",
        "history": [
            {
                "state": "CONFIRMED",
                "message": null,
                "displayName": "confirmed",
                "displayNameDescription": "The transaction has been confirmed",
                "created": "2018-04-05T16:01:56+02:00",
                "updated": "2018-04-05T16:01:56+02:00"
            },
            {
                "state": "QR_CODE_GENERATED",
                "message": null,
                "displayName": "pending",
                "displayNameDescription": "The transaction is pending",
                "created": "2018-04-05T16:01:08+02:00",
                "updated": "2018-04-05T16:01:08+02:00"
            },
            {
                "state": "INITIATED",
                "message": null,
                "displayName": "pending",
                "displayNameDescription": "The transaction is pending",
                "created": "2018-04-05T16:01:07+02:00",
                "updated": "2018-04-05T16:01:07+02:00"
            }
        ],
        "qr": {
            "id": "8d9de05a-38ea-11e8-88db-591e8a5a25ac",
            "fileName": "60a9ad0303e5f0634ffc0410c7527e20.png",
            "file": "https://cdn.pomelopay.com/qrcodes/60a9ad0303e5f0634ffc0410c7527e20.png",
        },
        "currentState": "CONFIRMED",
        "currentStateDetails": {
            "state": "CONFIRMED",
            "message": null,
            "displayName": "confirmed",
            "displayNameDescription": "The transaction has been confirmed",
        },
        "providersDetails": {
            "key": "POMELO",
            "displayName": "pomelo",
            "image": "https://s3-eu-west-1.amazonaws.com/pomelodev-shenzhen/providers/icon_pomelo.png"
        },
        "costStructure": {
            "id": "8da3d064-38ea-11e8-88db-591e8a5a25ac",
            "payable": 953,
            "fee": 47,
            "feeRate": 0.022,
            "feeRateExact": 0.047
        },
        "forwardUrl": "http://app.pomelopay.com/hooks/out/8d460a24-38ea-11e8-88db-591e8a5a25ac",
        "redirectUrl": null,
        "meta": null,
        "created": "2018-04-05T16:01:07+02:00",
        "updated": "2018-04-05T16:01:56+02:00",
        "amount": 1000,
        "currency": "GBP"
    },
    ...

This endpoints creates a new Transaction

HTTP Request

POST https://app.pomelopay.com/api/transactions

Query Parameters

This endpoint does not accept query parameters

Request body

Field	Description	Format
amount	transaction amount in cents	`int`
provider	payment provider for transaction, must be enabled	`string`
currency	transaction currency, must be company currency	3 letter ISO code
deviceId	your application id from your merchant portal	`string`
appVersion	free to use string to identify versions of your app	`string`

Response body

Field	Description	Format
id	unique id of the transaction	string
notes	notes added to this transaction	string
securityWord	security word that is added on confirmation	string
hashId	unique hashId of the transaction	string
appVersion	version of the app or API that was used to create this transaction	string
deviceId	id of the device or application that was used to create this transaction	string
provider	the payment provider used for this transaction	string
history	array of transactions states	array
qr	QR code information for this transaction	object
currentState	current state of the transaction	object
costStructure	detailed information about fees and rates	object
forwardUrl	URL to redirect to for payment completion	string
redirectUrl	optional redirect url to go after payment	string
amount	amount in cents for this transactions	int
currency	currency of this transaction	3 letter ISO code
meta	meta information key value format such as email or address	object

Errors

The following error status codes might be returned:

Error Code	Meaning
400	Bad Request -- Your request is invalid. See response body for validation errors.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- You don't have access to this resource
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- This endpoint does not accept the specified HTTP method
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.