Vend Service API

Request Format

The Vend Service API is REST based and communication is conducted over a HTTPS connection using TLS v1.2. The request, if required can also contain an additional basic access authentication  by  containing    'Authorization: Basic <credentials>',  in the header where credentials is a Base64 encoding of username:password    that you have provided.

Request/Response Headers

The header of the responses and the  requests that PayPoint  POSTs to your endpoint  contains the following:

• request-type -  Type of request  payment/reversal/refund  (optional)

• content-type -  We will send requests and receive responses  in the  application/json codec

• connection  - We will try to keep the connection always open (Keep-Alive), sending and receiving messages interlaced.

• x-request-id -   This is an unique id for the request  and must be returned in the response

• content-length -   The API does not support chunk messages; therefore, all the request and responses contain size of the entity-body, in bytes.

Request Body

The body  of the requests  that PayPoint  POSTs to your endpoint  contains the following parameters:

• transaction_id -  Transaction ID to identify the request - up  to 15  alphanumeric  characters

• original_transaction_id -  The transaction of the original request (reversal/refund only)  - up to 15  alphanumeric  characters

• amount -  The vend amount requested by the customer - fixed   12 digit number i.e.   000000001000 is £10.00

• pan -  Primary account number/Customer Id   - up to 19 digit number  i.e.  9826000001760704012

Vend Request

When a customer has made a payment request via the PayPoint Retail Network or our MultiPay Digital Service we will POST you a vend request to your endpoint. The vend request will contain details of the transaction including the customer's PAN and the amount of the payment, as shown below:

POST /payment HTTP/1.1
request-type:payment
content-type:application/json
connection:Keep-Alive
accept:application/json
x-request-id:0000007321
host:api.example.com:443
content-length:98
{
	"transaction_id":"PPT19000003",	
	"amount":"000000001000",
	"pan":"9826000001760704012"
}

Note: If you are making an immediate and un-reversible top-up to a customer account, we recommend that you wait  10 minutes between  receiving the vend request and applying the top-up to the account in order to allow for a possible reversal to occur.

Vend Request Response

Upon processing the vend request, you will need to return a 200 JSON response containing the result of your vend activity. The response must contain the   x-request-id  that matches the  vend request in the header, the transaction id of the request, the customers PAN and an appropriate response_code .

If we   do not receive a 200 response we will   fail the  vend request and inform the customer that  their payment  request has failed. We will also send you a vend reversal request.

HTTP/1.1 200 OK
request-type:payment
content-type:application/json
connection:Keep-Alive
accept:application/json
x-request-id:0000007321
content-length:250

{
	"transaction_id": "PPT19000003",
	"pan": "9826000001760704012",
	"response_code": "00",
	"amount": "000000001000",
	"message": "The Payment was successful. The account will be updated in maximum 10 min.",
	"code": "66940310250465240929"
}

Upon a successful vend  activity, you will need to return the response code  00, the vend code and the  message that you wish to print on the  paper  receipt   from the  PayPoint Retail Network Terminal.

• response_code   -   Code  indicating   if the vend was successful or  if an error has occurred -  fixed   2 digit number.  See  Response Codes. 

• message -  The message to be printed on the paper receipt from the  PayPoint Retail Network Terminal. The message field can be used in junction with the response code field where multiple error messages need to be printed on the receipt, based on the error type. If there is no need to differentiate the errors that a single response code can be used (preferred 05) with multiple messages - up  to 240 alphanumeric & special characters

• code -  The top-up/vend code or UTRN required by the customer - up  to 20  alphanumeric  characters

Vend Reversal Request

A vend request can fail to reach your endpoint or we fail to receive a vend response. In both cases we will send you a vend reversal request  within 10 minutes of sending the original vend request. In addition, if the terminal within the PayPoint Retail Network fails to receive the vend response within 28 seconds, the terminal will print a failed receipt and will also send a vend reversal request.

Because a vend reversal occurs as a consequence of an error, the request  is considered as advice of an event that has already taken place, and therefore can not be refused by your endpoint.

The vend reversal request will contain  the customer's PAN, amount and the original transaction id of the failed transaction, as shown below:

POST /reversal HTTP/1.1
request-type:reversal
content-type:application/json
connection:Keep-Alive
accept:application/json
x-request-id:0000007321
host:api.example.com:443
content-length:141
{
	"transaction_id":"PPT19000003",
	"amount":"000000001000",
	"original_transaction_id":"PPT19000002",
	"pan":"9826000001760704012"
}

Note: If the vend reversal request fails, we will keep sending the reversal request, every 30 seconds until we receive a response (the number of retries is configurable).

Vend Reversal Response

Upon receiving a vend reversal request, you must return a 200 JSON response containing the   x-request-id  that matches the  vend reversal request.

If the  original vend request fails to reach your endpoint and we send a reversal  request then  your reversal response shown contain  response_code  25  (unable to locate record).  If we or the terminal fails to receive  your vend response  then you will need to process the reversal and return a response_code 00 (success), as shown below:

HTTP/1.1 200 OK
request-type:reversal
content-type:application/json
connection:Keep-Alive
accept:application/json
x-request-id:0000007321
content-length:142
{
	"transaction_id": "PPT19000003",
	"original_transaction_id": "PPT19000002",
	"pan": "9826000001760704012",
	"response_code": "00",
}

Vend Refund Request

If transaction has been successful  and the customer  has received the  vend, the transaction   can no longer be  reversed,  however  the customer can request for a  refund. A vend refund request will only be sent  if  the refund request is with 10 minutes of the  original successful transaction.

The vend refund request will contain  the customer's PAN, amount and the original transaction id of the successful transaction as shown below:

POST /refund HTTP/1.1
request-type:refund
content-type:application/json
connection:Keep-Alive
accept:application/json
x-request-id:0000007321
host:api.example.com:443
content-length:139
{
	"transaction_id":"PPT19000003",    
	"amount":"000000001000",
	"original_transaction_id":"PPT19000002",
	"pan":"9826000001760704012
}

Vend Refund Response

Upon processing the vend refund request, you will need to return a 200 JSON response containing the result of your vend refund. The response must contain the   x-request-id  that matches the  vend refund request in the header, the transaction id of the request, and the original transaction id for the transaction that is being refunded. 

HTTP/1.1 200 OK
request-type:refund
content-type:application/json
connection:Keep-Alive
accept:application/json
x-request-id:0000007321
content-length:186

{
	"transaction_id": "PPT19000003",
	"original_transaction_id": "PPT19000002",
	"pan": "9826000001760704012",
	"response_code": "00",
	"message": "Payment successfully refunded.",

Upon a successful vend refund, you will need to return the response code  00, and the  message that you wish to print on the  paper  receipt   from the  PayPoint Retail Network Terminal. If you decide to refuse the refund request you should return  a response code  of 05.

Response Codes

In your 200 JSON response to a  vend request you will need to include a 2 digit numeric   response_code, as  described below:

• 00 - Approved or completed successfully

• 05 - Do not honor

• 06 - Error

• 12 - Invalid transaction

• 13 - Invalid amount

• 14 - Invalid card number

• 25 - Unable to locate record

• 26 - Duplicate record

• 48 - No customer record

Note:  Please contact your account manager, if you wish to add additional response codes or  not implement all the response codes listed above.