Pay it wise merchant api

To connect your application with our rest based api you will need to perform the following.

• be able to send http requests in json format and consume the responses also in json
• implement the varius operations including Payment, Refund and Enquiry
• understand basic REST api semantics

The initial step will be to connect your development environment to our test system and perform a full suite of operations you are planning to support. After we have verifeid your integration is working you will be moved to your production environment. See URLs for more details.

You can use any language or framework of your choice to perform the integration.

The full api reference is published as an OpenAPI schema and you can use this to test the api or generate client side code.

OpenAPI Schema

• https://api-stage.payitwise.com/schema/schema.yaml

To use the api you need to acquire an api key. Upon registration the api key will be provided to you and must be used in each api call to authenticate your merchant account.

The api key must be sent to the server via the Auhorized head with the value ‘Bearer {apiKey}’

Here is an example:

GET https://api-stage.payitwise.com/v1/payments/c7jauufm30rtsvudetg0 HTTP/1.1 

Authorization: Bearer {{token}}

Test URL

In order to test your integration you must use the following Test URL:

https://api-stage.payitwise.com

For example the full url for the Payment by id endpoint will be

https://api-stage.payitwise.com/v1/payments/{id}

Production URL

IN order to process live transactions you must use the following URL:

https://api.payitwise.com

For example the full url for the Payment by id endpoint will be

https://api.payitwise.com/v1/payments/{id}

The below token can be used in our test environment to start testing your integration immediatelly.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE5NTkwNjU2ODMsImlhdCI6MTY0MzcwNTY4MywibWVyY2hhbnRJZCI6IjEiLCJzdWIiOiJyZXBheSJ9._3huFupBGgt0jBuLxktV80IjY5zhBH_RkFoMQOSjK8k

Payments

A payment is when a merchant wants to redeem a voucher. The value of the voucher will be transferred to the merchant account minus the processing fee. After the voucher has been redeemed it can no longer be used. The merchant will then have to credit the customer account on their system with the value of the voucher amount in the designated currency.

See the payment operation specification for more details

Refunds

If for whatever reason the merchant want to reverse the charge to the customer, they can use the refund function. The refund is not available by default and must be requested by the merchant. Since the voucher cannot be used after it has been redeemed the refund operation will issue a new voucher and give it to the customer. The voucher will be sent to the customer who had originally purchased the vouchere being refunded.

This feature is under development

Enquiries

A merchant can check the status of a previously completed transaction or refund by querying the api by the transaction status. See payment by id for more information.

Customer Details

To ensure security and compliance with regulations we must have full customer details with each transactional request. This includes the full customer details. The following are required parameters. These will be used to prevent fraud and regulatory abuse. In addition any client complants and refunds must have valid details.

• customerId must be a unique identifer of the customer on the merchant system, two transactions for the same customer must have the same customer id
• fullName is the complete legal name of the customer including givenName, surname, middle name titles etc
• email is the email the client has used to register at the merchant system
• phoneNumber is the telephone number, with mobile number preffered if multiple numbers are available
• ipAddress is the internet address of the customer as seem when they are visiting the merchant web site

{
    "customer": {
        "customerId": "c7jauufm30rtsvudetg0",
        "fullName": "Joe Doe",
        "email": "joe@example.com",
        "phoneNumber": "+442233445566",
        "ipAddress": "0.0.0.0"
    },
    "customerAddress": {
        "country": "GB",
        "city": "London",
        "area": "Greater London",
        "code": "SW1W 0NY",
        "address": "Street name"
    }
}

Response fields

All api response contain the following fields

• status the overal request status, can be one of ok, error
• error if status is not ok error will contain an error code explaing what the failure was
• data when status is ok data will contain the valid response, when status is error data may contain more details about the error

Error codes list

• error/not_found the requested resource was not found on the server
• payment/duplicate the payment contained a merchantTransactionId which was previously used
• payment/declined the payment was declined, this means that the voucher code was not in an AVAILABLE state

Example success:

{
    "status": "ok",
    "data": {
        "responseCode": "SUCCESS",
        "transactionId": "c7sfq27rvchheam4pkj0"
    }
}

Example error:

{
    "status": "error",
    "error": "payment/declined"
}

Some working code examples to make api requests

Redeem a voucher

Example code in javascript

var crypto = require('crypto');
var request = require('request');

var requestId = crypto.randomBytes(16).toString('hex');
var options = {
    'method': 'POST',
    'url': 'https://api-stage.payitwise.com/v1/payments',
    'headers': {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsIn...'
    },
    body: JSON.stringify({
        "merchantTransactionId": requestId,
        "voucherCode": "8000000000000000",
        "customer": {
            "customerId": "c7jauufm30rtsvudetg0",
            "fullName": "Joe Doe",
            "email": "joe@example.com",
            "phoneNumber": "+442233445566",
            "ipAddress": "0.0.0.0"
        },
        "customerAddress": {
            "country": "GB",
            "city": "London",
            "area": "Greater London",
            "code": "SW1W 0NY",
            "address": "Street 1b"
        }
    })

};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
    var responseBody = JSON.parse(response.body);
    if (responseBody.status == "ok" && responseBody.data.responseCode == "SUCCESS") {
        console.log("Transaction success");
    } else {
        console.log("Transaction declined:", responseBody.error);
    }
});

Response:

{
    "status": "ok",
    "data": {
        "amount": "200.00",
        "amountCredited": "192.00",
        "currency": "EUR",
        "fee": "8.00",
        "merchantTransactionId": "db1d954ac7d2338997d6d2f855546cd2",
        "responseCode": "SUCCESS",
        "transactionId": "c7sfq27rvchheam4pkj0"
    }
}

Query status of a transaction

Example code in javascript

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'http://api-stage.payitwise.com/v1/payments/c7sfq27rvchheam4pkj0',
    'headers': {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsIn...'
    },
};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);

    var responseBody = JSON.parse(response.body);
    if (responseBody.status == "ok" && responseBody.data.responseCode == "SUCCESS") {
        console.log("Transaction success");
    } else {
        console.log("Transaction declined:", responseBody.error);
    }
});

Response:

{
    "status": "ok",
    "data": {
        "amount": "200.00",
        "amountCredited": "192.00",
        "currency": "EUR",
        "fee": "8.00",
        "merchantTransactionId": "db1d954ac7d2338997d6d2f855546cd2",
        "responseCode": "SUCCESS",
        "transactionId": "c7sfq27rvchheam4pkj0"
    }
}