Introduction

Welcome to the ProxyPay API! This API allows developers to easily integrate with Multicaixa to accept payments. You have endpoints to generate numeric references for payments and to receive notification of payments when they occur.

The ProxyPay API is organized around REST. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

Authentication

You authenticate to the ProxyPay API by providing your API key in the request. Be sure to keep it a secret!

Authentication to the API occurs via HTTP Basic Auth. Provide api as the basic auth username and your API key as the password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

To authorize, use this code:

curl "https://api.proxypay.co.ao" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2"

Make sure to replace reh8inj33o3algd2tpi6tkcnrqf8rjj2 with your own API key.

Versioning

By default, all requests receive the latest version of the API, which is currently v2. We encourage you to explicitly request this version via the Accept header.

curl "https://api.proxypay.co.ao" \
  -H 'Accept: application/vnd.proxypay.v1+json'

References

A reference must be created whenever you want to receive a payment of a given amount.

To create one you must specify at least an amount and an expiry date. Additionaly you can specify any number of custom_fields.

A reference will have the following attributes (all attributes, except custom_fields, have JSON strings as values):

Get All References

curl "https://api.proxypay.co.ao/references" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2"

The above command returns JSON structured like this:

{
  "references": [
    {
      "status": "active",
      "number": "664654696",
      "id": "8uW7O0N4LvOuQsYAFc",
      "expiry_date": "2015-11-05",
      "custom_fields": {
        "invoice": "2015/0121"
      },
      "amount": "5000.00"
    },
    {
      "status": "deleted",
      "number": "234123215",
      "id": "8uVlQn87qCPnF9U3Um",
      "expiry_date": "2015-02-15",
      "custom_fields": {
        "invoice": "2015/0145"
      },
      "amount": "12222.00"
    },
    {
      "status": "paid",
      "number": "283749832",
      "id": "8uVigNJ7Jj4hvVMdhQ",
      "expiry_date": "2015-02-28",
      "custom_fields": {
        "invoice": "2015/0118"
      },
      "amount": "5000.00"
    },
    {
      "status": "expired",
      "number": "293840932",
      "id": "8uUIvA8jlPKnSwwKPI",
      "expiry_date": "2014-12-12",
      "custom_fields": {
        "invoice": "2014/0097"
      },
      "amount": "11123.23"
    }
  ],
  "meta": {
    "total_count": 4,
    "offset": 0,
    "limit": 20
  }
}

This endpoint retrieves all references in the system, sorted by descending order of creation date.

HTTP Request

GET https://api.proxypay.co.ao/references

Query Parameters

Get a Specific Reference

curl "https://api.proxypay.co.ao/references/8uVigNJ7Jj4hvVMdhQ" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2"

The above command returns JSON structured like this:

{
  "reference": {
    "updated_at": "2015-02-20T17:30:00Z",
    "status": "paid",
    "number": "283749832",
    "id": "8uVigNJ7Jj4hvVMdhQ",
    "expiry_date": "2015-02-28",
    "entity_id": "99999",
    "custom_fields": {
      "invoice": "2014/0097"
    },
    "created_at": "2015-02-01T08:36:37Z",
    "amount": "5000.00"
  }
}

This endpoint retrieves a specific reference.

HTTP Request

GET https://api.proxypay.co.ao/references/<ID>

URL Parameters

Generate a New Reference

curl -XPOST "https://api.proxypay.co.ao/references" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Content-Type: application/json' \
  -d '{"reference": { "amount": "25000.00", "expiry_date": "2015-05-15", "custom_fields": {"invoice": "2015/0399"}}}'

The above command returns JSON structured like this:

{
  "reference": {
    "updated_at": "2015-05-10T17:43:10Z",
    "status": "active",
    "number": "892374833",
    "id": "8uWqsbFsHNUzS19DY8",
    "expiry_date": "2015-05-15",
    "entity_id": "99999",
    "custom_fields": {
      "invoice": "2015/0399"
    },
    "created_at": "2015-05-10T17:43:10Z",
    "amount": "25000.00"
  }
}

This endpoint generates a new payment reference for a given amount.

HTTP Request

POST https://api.proxypay.co.ao/references

URL Parameters

Payment Events - Pull API

This endpoint can be used to fetch any new payment events that occured in the system. It works conceptually as a queue, and all payments are returned in the order they ocurred.

You can retrieve up to 100 payments in a single call. Each request will return all unacknowledged payments unless visibility_timeout is specified, in which case all payments returned will be reserved for visibility_timeoutseconds, meaning that they are not returned in a subsequent call to the endpoint. If an acknowledgement indicating that they have been sucessfully processed is not sent within that timeframe, they will become available again.

A Payment event will have the following attributes (all attributes, except custom_fields, have JSON strings as values):

Fetch New Payments

curl "https://api.proxypay.co.ao/events/payments" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2"

The above command returns JSON structured like this:

{
  "payments": [
    {
      "terminal_type": "01",
      "terminal_transaction_id": "00123",
      "terminal_location": "Luanda",
      "terminal_id": "00456",
      "reference_number": "283749832",
      "reference_id": "8uVigNJ7Jj4hvVMdhQ",
      "id": "449500352608",
      "entity_id": "99999",
      "datetime": "2015-05-10T17:43:10Z",
      "custom_fields": {
        "invoice": "2014/0097"
      },
      "amount": "5000.00"
    }
  ]
}

This endpoint retrieves all Payment events that have not been acknowledged.

HTTP Request

GET https://api.proxypay.co.ao/events/payments

Query Parameters

Acknowledge a Payment

curl -XDELETE "https://api.proxypay.co.ao/events/payments/449500352608" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2"

The above command returns HTTP Status 204 No Content.

This endpoint acknowledges that a specific payment has been processed.

HTTP Request

DELETE https://api.proxypay.co.ao/events/payments/<ID>

URL Parameters

Note: If your HTTP client doesn't allow sending a request with the HTTP verb DELETE, you can use POST instead and pass the additional URL parameter _method=delete.

Acknowledge Multiple Payments

curl -XDELETE "https://api.proxypay.co.ao/events/payments" \
  -u "api:reh8inj33o3algd2tpi6tkcnrqf8rjj2"
  -H 'Content-Type: application/json'
  -d '{"ids": ["449500352608", "449500352609"]}'

The above command returns HTTP Status 204 No Content.

This endpoint acknowledges that multiple payments have been processed.

HTTP Request

DELETE https://api.proxypay.co.ao/events/payments

URL Parameters

Note: If your HTTP client doesn't allow sending a request with the HTTP verb DELETE, you can use POST instead and pass the additional URL parameter _method=delete.

Payment Events - Push API

As an alternative to the Pull API, ProxyPay can instead push new payment events to a URL provided by you.

You must provide an HTTP or HTTPS endpoint that is publicly accessible over the Internet.

Callback

Your callback endpoint will receive the data encoded as JSON.

In some situations, such as a timeout when calling your endpoint, the same payment may be submitted multiple times. You should make sure your logic is idempotent.

To authenticate the request, we include an HMAC-SHA-256 signature in every request. In addition to all the attributes of the payment event, already detailed in the Pull API, we also submit the following extra attributes:

Your endpoint will receive a POST request with a JSON structured like this:

{
  "payment": {
    "terminal_type": "01",
    "terminal_transaction_id": "00123",
    "terminal_location": "Luanda",
    "terminal_id": "00456",
    "reference_number": "283749832",
    "reference_id": "8uVigNJ7Jj4hvVMdhQ",
    "id": "449500352608",
    "entity_id": "99999",
    "datetime": "2015-05-10T17:43:10Z",
    "custom_fields": {
      "invoice": "2014/0097",
      "customer_name": "Acme"
    },
    "amount": "5000.00"
  },
  "meta": {
    "timestamp": "1428262214",
    "signature": "809427D33F649EDB8A7C123D76E5B426C37DFE6B56C9160509CFCAA01C86F844"
  }
}

Your endpoint must return HTTP Status 200 after successfully processing the event. Any other status code will be considered an error and ProxyPay will retry after 10 minutes.

The checksum_data is calculated by appending the values of all attributes in the following order:

checksum_data = amount + datetime + entity_id + id + reference_id + reference_number + terminal_id + terminal_location + terminal_transaction_id + terminal_type + custom_fields_in_alphabetical_order

In the example, customer_fields_in_alphabetical_order = customer_name + invoice

Example

API Key

h5a4e6ctej01hn9agh7uggt5n8r29ups

timestamp

1428262214

checksum_data

5000.002015-05-10T17:43:10Z999994495003526088uVigNJ7Jj4hvVMdhQ28374983200456Luanda0012301Acme2014/0097

signature

809427D33F649EDB8A7C123D76E5B426C37DFE6B56C9160509CFCAA01C86F844

signature == HMAC-SHA-256(API Key, timestamp+checksum_data)

HTTP Request

POST http(s)://<your callback url>

Query Parameters

Validating the Signature

To validate the signature, simply calculate the expected signature using HMAC-SHA-256, compare it to the signature in the request and reject the data if they are different.

Errors

The ProxyPay API uses the following error codes: