Receive a payment

Overview

Once a funding source has been created, it can bee used to add funds to a customers wallet.

Initiating a payment

1. Get the ID of the funding source

Funding sources that belong to a customer can be queried by a call to GET /api/Customers/{id}/sources.

Which will return an array fo funding source objects as shown below.

{
    "accountNumber": "string",
    "sortCode": "string",
    "links": {},
    "id": "string",
    "externalId": "string",
    "type": "DebitCard",
    "name": "string",
    "cardNumber": "string",
    "cvc": 0,
    "expMonth": 0,
    "expYear": 0,
    "cardHolderName": "string",
    "bankName": "string",
    "branchAddress1": "string",
    "branchAddress2": "string",
    "branchAddress3": "string",
    "branchTown": "string",
    "branchPostcode": "string"
  }
]

Using the ID from the above request construct a new JSON object

2. Construct a new request

To create a new source different data are required depending on the source type.

For Debit Cards

Field Name	Description
sourceId	The id of the funding source to take payment from
walletId	The id of the vault into which funds should be deposited
amount	The amount to take from the card

This data should be formatted as a JSON object as shown below.

{
  "sourceId": "string",
  "walletId": "string",
  "amount": 0
}

3. Send your request

Once you have created the above object you can send it as the body of a post request to the POST /api/Payments end point

var data = JSON.stringify(Mdeol);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://example.com/api/Payments");

xhr.send(data);

If the request is successful the response body will contain the following information

{
  "timestamp": "2017-06-08T12:39:58.059Z",
  "links": {},
  "id": "string",
  "amount": 0,
  "wallet": {
    "links": {},
    "id": "string",
    "holderId": "string",
    "number": "string",
    "name": "string",
    "status": "Open",
    "statusReason": "string",
    "balance": 0,
    "opened": "2017-06-08T12:39:58.059Z",
    "currencyCode": "string"
  },
  "source": {
    "accountNumber": "string",
    "sortCode": "string",
    "links": {},
    "id": "string",
    "externalId": "string",
    "type": "DebitCard",
    "name": "string",
    "cardNumber": "string",
    "cvc": 0,
    "expMonth": 0,
    "expYear": 0,
    "cardHolderName": "string",
    "bankName": "string",
    "branchAddress1": "string",
    "branchAddress2": "string",
    "branchAddress3": "string",
    "branchTown": "string",
    "branchPostcode": "string"
  },
  "status": "Success",
  "statusReason": "string",
  "expectedCompletionDate": "2017-06-08T12:39:58.060Z",
  "history": [
    {
      "timestamp": "2017-06-08T12:39:58.060Z",
      "status": "Success",
      "statusReason": "string",
      "providerReference": "string"
    }
  ]
}

The response object contains a history property which is an array of objects representing the state of the payment at certain times.

Some payment methods (ie. Debit cards will succeed or fail immediately and therefore have only one history record.

Others (ie Bank Transfer) may take several days to complete. The history for these payments will show that the request was pending before moving through to either the failed, or pending status.

Clients should use a web hook to monitor for a payment status change to update their systems if required