Introduction

Welcome to the ProxyPay API V2!

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.

The current ProxyPay REST API integration version is v2.

The following table shows API versions currently supported:

API Version	Documentation
v2	Current document
v1	v1 docs

API Format

curl "https://api.proxypay.co.ao" \
  -H 'Content-Type: application/json'

PUT / HTTP/1.1
Content-Type: application/json

All request bodies should have content type application/json and be valid JSON. The Content-Type header must be set in all requests that include a JSON body:

Content-Type: application/json

Endpoints

Environment	Base URL
Production	https://api.proxypay.co.ao
Sandbox	https://api.sandbox.proxypay.co.ao

Versioning

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

PUT / HTTP/1.1
Accept: application/vnd.proxypay.v2+json
Content-Type: application/json

By default, all requests receive the latest version of the API. We encourage you to explicitly lock the client application to a version by including the Accept header in all requests:

Accept: application/vnd.proxypay.v2+json

Authentication

To authenticate, provide the API Key in the request header:

curl "https://api.proxypay.co.ao" \
  -H 'Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2' \
  -H 'Accept: application/vnd.proxypay.v2+json' \
  -H 'Content-Type: application/json'

PUT / HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json
Content-Type: application/json

Make sure to replace reh8inj33o3algd2tpi6tkcnrqf8rjj2 in the example with your own API Key.

You authenticate to the ProxyPay API by providing your API Key in the Authorization header of every request:

Authorization: Token [YOUR_API_KEY]

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Errors

Status Code	Meaning
400	Bad Request – Your request is invalid.
401	Unauthorized – Your API key is wrong.
404	Not Found – The specified resource could not be found.
405	Method Not Allowed – You tried to access a resource with an invalid method.
406	Not Acceptable – You requested a format that isn't supported.
429	Too Many Requests – You've making too many requests to the API. Slow down!
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.

Validation Errors

Any invalid input parameter will cause a 400 - Bad Request response. The JSON Response includes a list of human readable descriptions of the errors with the following structure:

Name	Type	Required	Description
param	string	true	Invalid Parameter
message	string	true	Human readable error message

Webhooks

ProxyPay can also POST data to your application when Payment events occur. You can read more about the Payment Webhook below.

Resources

The resources are Collections or Elements. A collection represents the set of all resources of a particular type (such as "references" or "payments"). An element resource represents an individual member of a collection. Each element consists of a set of name/value pairs.

References

Create or Update Reference

Creating/Updating a reference with Id 904800000 and setting the amount, date limit and custom_fields.

curl -XPUT "https://api.proxypay.co.ao/references/904800000" \
  -H "Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Accept: application/vnd.proxypay.v2+json' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "9701.84",
    "end_datetime": "2018-12-31",
    "custom_fields": {
      "invoice": "2018/0333"
      }
    }'

PUT /references/904800000 HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json
Content-Type: application/json

{
  "amount": "9701.84",
  "end_datetime": "2018-12-31",
  "custom_fields": {
    "invoice": "2018/0333"
  }
}

<?php
$reference = [
    "amount"        => "9701.84",
    "end_datetime"  => "2018-12-31",
    "custom_fields" => [
      "invoice" => "2018/0333"
    ]
];

$data = json_encode($reference);

$curl = curl_init();

$httpHeader = [
    "Authorization: " . "Token " . "reh8inj33o3algd2tpi6tkcnrqf8rjj2",
    "Accept: application/vnd.proxypay.v2+json",
    "Content-Type: application/json",
    "Content-Length: " . strlen($data)
];

$opts = [
    CURLOPT_URL             => "https://api.proxypay.co.ao/references/904800000",
    CURLOPT_CUSTOMREQUEST   => "PUT",
    CURLOPT_HTTP_VERSION    => CURL_HTTP_VERSION_1_1,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_TIMEOUT         => 30,
    CURLOPT_HTTPHEADER      => $httpHeader,
    CURLOPT_POSTFIELDS      => $data
];

curl_setopt_array($curl, $opts);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
?>

JSONObject custom_fields = new JSONObject();
custom_fields.put("invoice", "2018/0333");

JSONObject reference = new JSONObject();

reference.put("amount", "9701.84")
  .put("end_datetime", "2018-12-31")
  .put("custom_fields", custom_fields);

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, reference.toString());
Request request = new Request.Builder()
    .url("https://api.proxypay.co.ao/references/904800000")
    .put(body)
    .addHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2")
    .addHeader("Accept", "application/vnd.proxypay.v2+json")
    .addHeader("Content-Type", "application/json")
    .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://api.proxypay.co.ao/references/904800000");

var request = new RestRequest(Method.PUT);

request.RequestFormat = DataFormat.Json;

request.AddHeader("Accept", "application/vnd.proxypay.v2+json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2");

request.AddBody(new {
  amount = "9701.84",
  end_datetime = "2018-12-31",
  custom_fields = new {
    invoice = "2018/0333"
  }
});

IRestResponse response = client.Execute(request);

The call above returns HTTP Status Code 204 if the Reference was successfully created/updated

HTTP/1.1 204 No Content

This endpoint creates or updates a payment reference with given Id.

HTTP Request

PUT /references/{id}

URL Parameters

Parameter	Type	Required	Description
id	integer	true	Reference Id (1)

Payload

Name	Type	Required	Description
amount	string	false	The amount to be paid (must be between 0.01 and 99999999.99)
end_datetime	string	false	Expiration Date or Datetime formatted as ISO8601; if Date notation is used the reference will be valid until 23:59:59, assuming GMT+1 timezone
custom_fields	map	false	A key-value structure with up to 10 custom fields; Key and Value must be strings; this map is copied over to the Payment

Responses

Status	Meaning	Description
204	No Content	Reference was created or updated successfully
4xx or 5xx	Error	Please check errors list here

Delete Reference

Deleting a reference with Id 904800000:

curl -X DELETE "https://api.proxypay.co.ao/references/904800000" \
  -H "Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Accept: application/vnd.proxypay.v2+json'

DELETE /references/904800000 HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json

<?php
$curl = curl_init();

$httpHeader = [
    "Authorization: " . "Token " . "reh8inj33o3algd2tpi6tkcnrqf8rjj2",
    "Accept: application/vnd.proxypay.v2+json",
];

$opts = [
    CURLOPT_URL             => "https://api.proxypay.co.ao/references/904800000",
    CURLOPT_CUSTOMREQUEST   => "DELETE",
    CURLOPT_HTTP_VERSION    => CURL_HTTP_VERSION_1_1,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_TIMEOUT         => 30,
    CURLOPT_HTTPHEADER      => $httpHeader
];

curl_setopt_array($curl, $opts);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
?>

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
    .url("https://api.proxypay.co.ao/references/904800000")
    .delete()
    .addHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2")
    .addHeader("Accept", "application/vnd.proxypay.v2+json")
    .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://api.proxypay.co.ao/references/904800000");

var request = new RestRequest(Method.DELETE);

request.AddHeader("Accept", "application/vnd.proxypay.v2+json");
request.AddHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2");

IRestResponse response = client.Execute(request);

The call above returns HTTP Status Code 204

HTTP/1.1 204 No Content

This endpoint deletes a reference with given Id.

HTTP Request

DELETE /references/{id}

URL Parameters

Parameter	Type	Required	Description
id	int	true	Reference Id

Responses

Status	Meaning	Description
204	No Content	Reference was deleted
4xx or 5xx	Error	Please check errors list here

Reference Ids

Generate Reference Id

The following call returns a unique reference Id

curl -X POST "https://api.proxypay.co.ao/reference_ids" \
  -H "Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Accept: application/vnd.proxypay.v2+json'

POST /reference_ids HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json

<?php
$curl = curl_init();

$httpHeader = [
    "Authorization: " . "Token " . "reh8inj33o3algd2tpi6tkcnrqf8rjj2",
    "Accept: application/vnd.proxypay.v2+json",
];

$opts = [
    CURLOPT_URL             => "https://api.proxypay.co.ao/reference_ids",
    CURLOPT_CUSTOMREQUEST   => "POST",
    CURLOPT_HTTP_VERSION    => CURL_HTTP_VERSION_1_1,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_TIMEOUT         => 30,
    CURLOPT_HTTPHEADER      => $httpHeader
];

curl_setopt_array($curl, $opts);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
?>

Request request = new Request.Builder()
    .url("https://api.proxypay.co.ao/reference_ids")
    .post(RequestBody.create(null, new byte[0]))
    .addHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2")
    .addHeader("Accept", "application/vnd.proxypay.v2+json")
    .build();

var client = new RestClient("https://api.proxypay.co.ao/reference_ids");

var request = new RestRequest(Method.POST);

request.AddHeader("Accept", "application/vnd.proxypay.v2+json");
request.AddHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2");

IRestResponse response = client.Execute(request);

The call above returns HTTP Status Code 200 and a JSON formatted list

475545250

HTTP/1.1 200 OK
Content-Type: application/json

475545250

This endpoint is provided for convenience and allows the generation of a Reference Id. The generator implements an LFSR and produces an out of order sequence of maximum length (the sequence repeats only once all possible Ids have been produced).

You may use it if you don't want to implement logic to generate unique Ids on the client-side.

HTTP Request

POST /reference_ids

Responses

Status	Meaning	Description
200	OK	Returns a unique Reference Id
4xx or 5xx	Error	Please check errors list here

Response Schema

Status Code 200

Name	Type	Required	Description
id	integer	true	Reference Id

Payments

This endpoint allows fetching any Payment events stored on the server. It exposes a persistent queue, allowing the client application to fetch up to 100 events.

After successfully processing a Payment event, the client application must Acknowledge it and discard it from the queue.

Get Payments

The following call returns any queued payments as a list

curl -X GET "https://api.proxypay.co.ao/payments" \
  -H "Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Accept: application/vnd.proxypay.v2+json'

GET /payments HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json

<?php
$curl = curl_init();

$httpHeader = [
    "Authorization: " . "Token " . "reh8inj33o3algd2tpi6tkcnrqf8rjj2",
    "Accept: application/vnd.proxypay.v2+json",
];

$opts = [
    CURLOPT_URL             => "https://api.proxypay.co.ao/payments",
    CURLOPT_CUSTOMREQUEST   => "GET",
    CURLOPT_HTTP_VERSION    => CURL_HTTP_VERSION_1_1,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_TIMEOUT         => 30,
    CURLOPT_HTTPHEADER      => $httpHeader
];

curl_setopt_array($curl, $opts);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
?>

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.proxypay.co.ao/payments")
  .get()
  .addHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2")
  .addHeader("Accept", "application/vnd.proxypay.v2+json")
  .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://api.proxypay.co.ao/payments");

var request = new RestRequest(Method.GET);

request.AddHeader("Accept", "application/vnd.proxypay.v2+json");
request.AddHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2");

IRestResponse response = client.Execute(request);

The call above returns HTTP Status 200 and JSON formatted list of Payments

[
  {
    "transaction_id": 26356,
    "terminal_type": "IB",
    "terminal_transaction_id": 0,
    "terminal_location": null,
    "terminal_id": 4644327306,
    "reference_id": 111111139,
    "product_id": null,
    "period_start_datetime": "2007-03-13T19:00:00Z",
    "period_id": 1562,
    "period_end_datetime": "2007-03-14T19:00:00Z",
    "parameter_id": null,
    "id": 156200026356,
    "fee": "50.00",
    "entity_id": 411,
    "datetime": "2017-01-17T09:08:00Z",
    "custom_fields": {},
    "amount": "1000.01"
  },
  {
    "transaction_id": 11938,
    "terminal_type": "ATM",
    "terminal_transaction_id": 1631,
    "terminal_location": "EMIS",
    "terminal_id": 550101,
    "reference_id": 501738711,
    "product_id": 1,
    "period_start_datetime": "2007-04-21T19:00:00Z",
    "period_id": 1601,
    "period_end_datetime": "2007-04-22T19:00:00Z",
    "parameter_id": 0,
    "id": 160100011938,
    "fee": "62.50",
    "entity_id": 411,
    "datetime": "2017-05-08T08:38:41Z",
    "custom_fields": {
      "name": "João Silva",
      "invoice": "2017/TBOX/001"
    },
    "amount": "25000.67"
  }
]

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "transaction_id": 26356,
    "terminal_type": "IB",
    "terminal_transaction_id": 0,
    "terminal_location": null,
    "terminal_id": 4644327306,
    "reference_id": 111111139,
    "product_id": null,
    "period_start_datetime": "2007-03-13T19:00:00Z",
    "period_id": 1562,
    "period_end_datetime": "2007-03-14T19:00:00Z",
    "parameter_id": null,
    "id": 156200026356,
    "fee": "50.00",
    "entity_id": 411,
    "datetime": "2017-01-17T09:08:00Z",
    "custom_fields": {},
    "amount": "1000.01"
  },
  {
    "transaction_id": 11938,
    "terminal_type": "ATM",
    "terminal_transaction_id": 1631,
    "terminal_location": "EMIS",
    "terminal_id": 550101,
    "reference_id": 501738711,
    "product_id": 1,
    "period_start_datetime": "2007-04-21T19:00:00Z",
    "parameter_id": 0,
    "period_id": 1601,
    "period_end_datetime": "2007-04-22T19:00:00Z",
    "parameter_id": 0,
    "id": 160100011938,
    "fee": "62.50",
    "entity_id": 411,
    "datetime": "2017-05-08T08:38:41Z",
    "custom_fields": {
      "name": "João Silva",
      "invoice": "2017/TBOX/001"
    },
    "amount": "25000.67"
  }
]

This endpoint returns any Payment events stored on the server that were not yet Acknowledged by the client application.

HTTP Request

GET /payments[?n=100]

URL Parameters

Parameter	Type	Required	Description
n	integer	false	Specifies the number of Payments to return (defaults to `100`; accepts any integer between `1` and `100`)

Responses

Status	Meaning	Description
200	OK
4xx or 5xx	Error	Please check errors list here

Response Schema

Status Code 200

Returns a list of elements with the following structure:

Name	Type	Nullable	Max. Length	Description
id	integer	no	12	Payment Id
amount	string	no	–	Payment amount
custom_fields	map	no	–	Key-value structure copied from the Reference
datetime	string	no	–	Payment datetime formatted as ISO8601
entity_id	integer	no	5	Entity Id
fee	string	yes	–	Bank fee
period_id	integer	no	4	Period Id
period_start_datetime	string	no	–	Start datetime of the Period
period_end_datetime	string	no	–	End datetime of the Period
period_id	integer	no	4	Period Id
product_id	integer	yes	2	Id of selected product (applicable if entity has multiple products)
parameter_id	integer	yes	2	Id of selected predefined amount (applicable if entity is configured to use predefined amounts)
reference_id	integer	no	–	Reference Id that originated the Payment
transaction_id	integer	no	8	Unique transaction Id within the Period
terminal_type	string	no	–	Type of terminal used for the payment (one of: `ATM`, `POS`, `IB`, `MB`)
terminal_period_id	integer	yes	3	Terminal period (only applicable when terminal_type is `ATM` or `POS`)
terminal_transaction_id	integer	yes	5	Terminal transaction (only applicable when terminal_type is `ATM` or `POS`)
terminal_location	string	yes	15	Location as informed by the payment processor (only applicable when terminal_type is `ATM` or `POS`)
terminal_id	string	yes	10	Id of the payment terminal (only applicable when terminal_type is `ATM` or `POS`)

Acknowledge Payment

The following call acknowledges that the payment with Id 160100011938 was processed on the client-side, effectivelly discarding it from the queue on the server

curl -X DELETE "https://api.proxypay.co.ao/payments/160100011938" \
  -H "Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Accept: application/vnd.proxypay.v2+json'

DELETE /payments/160100011938 HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json

<?php
$curl = curl_init();

$httpHeader = [
    "Authorization: " . "Token " . "reh8inj33o3algd2tpi6tkcnrqf8rjj2",
    "Accept: application/vnd.proxypay.v2+json",
];

$opts = [
    CURLOPT_URL             => "https://api.proxypay.co.ao/payments/160100011938",
    CURLOPT_CUSTOMREQUEST   => "DELETE",
    CURLOPT_HTTP_VERSION    => CURL_HTTP_VERSION_1_1,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_TIMEOUT         => 30,
    CURLOPT_HTTPHEADER      => $httpHeader
];

curl_setopt_array($curl, $opts);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
?>

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
    .url("https://api.proxypay.co.ao/payments/160100011938")
    .delete()
    .addHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2")
    .addHeader("Accept", "application/vnd.proxypay.v2+json")
    .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://api.proxypay.co.ao/payments/160100011938");

var request = new RestRequest(Method.DELETE);

request.AddHeader("Accept", "application/vnd.proxypay.v2+json");
request.AddHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2");

IRestResponse response = client.Execute(request);

The call above returns HTTP Status Code 204

HTTP/1.1 204 No Content

This endpoint is used to acknowledge that a payment was processed, after being retrieved using Get Payments, and discards it from the server.

HTTP Request

DELETE /payments/{id}

URL parameters

Parameter	Type	Required	Description
id	integer	true	Payment Id to acknowledge as processed

Responses

Status	Meaning	Description
204	No content	Success
4xx or 5xx	Error	Please check errors list here

Webhook

As an alternative to periodically fetching Payment events, ProxyPay can instead be configured to send new Payment events via HTTP(S) POST directly to your application.

POST / HTTP/1.1
X-Signature: b2faea0b081025ab55881e7684615c3920d2c67b4694c6ff770b5225c9fd464c
Content-Type: application/json

{
  "transaction_id": 26356,
  "terminal_type": "IB",
  "terminal_transaction_id": 0,
  "terminal_location": null,
  "terminal_id": "4644327306",
  "reference_id": 111111139,
  "product_id": null,
  "period_start_datetime": "2007-03-13T19:00:00Z",
  "period_id": 1562,
  "period_end_datetime": "2007-03-14T19:00:00Z",
  "parameter_id": 0,
  "id": 156200026356,
  "fee": "50.00",
  "entity_id": 411,
  "datetime": "2017-01-17T09:08:00Z",
  "custom_fields": {},
  "amount": "1000.01"
}

<?php
$api_key = "reh8inj33o3algd2tpi6tkcnrqf8rjj2";

$input = @file_get_contents("php://input");
$header_signature = $_SERVER['HTTP_X_SIGNATURE'];

$signature = hash_hmac('sha256', $input, $api_key);

if ( $signature == $header_signature )
{
    $payment = json_decode($input);

    // handle payment event

    http_response_code(204);
} else {
    http_response_code(400);
}
?>

package net.morgz;
import static spark.Spark.get;
import spark.Request;
import spark.Response;
import spark.Route;

public class Main {
  public static void main(String[] args) {
    POST(new Route("/payment_notification") {
      @Override
      public Object handle(Request request, Response response) {
        String api_key = "reh8inj33o3algd2tpi6tkcnrqf8rjj2";

        String header_signature = request.headers("X-Signature");
        String body = request.body()

        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(api_key.getBytes("UTF-8"), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        String signature = Hex.encodeHexString(sha256_HMAC.doFinal(body.getBytes("UTF-8")));

        if ( header_signature.equals(signature) )
        {
          JSONObject jsonObj = new JSONObject(body)

          // handle payment event

          response.status(204);
        } else {
          response.status(400);
        }
      }
    });
  }
}

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

Your endpoint will receive the Payment data encoded as JSON.

To acknowledge receipt, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to ProxyPay that you did not receive the Payment. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure.

On failure, ProxyPay will continue to retry at increasing intervals. ProxyPay will ignore any other information returned in the response headers or response body.

In some situations, such as a timeout when calling your endpoint, the same Payment may be sent multiple times. You should make sure your logic is able to detect and ignore duplicates, by simply acknowledging without processing it again.

To authenticate the request, we include an HMAC-SHA-256 signature, encoded as lowercase hexadecimal string, in the X-Signature header of every request.

Validating the Signature

To validate the signature, simply calculate the expected signature using the function below, compare it to the X-Signature header and reject the data if they are different.

signature == HexEncode(HMAC-SHA-256(your API Key, raw HTTP body))

Create a Mock Payment

Creating a mock payment for Reference Id 904800000:

curl -XPOST "https://api.proxypay.co.ao/payments" \
  -H "Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2" \
  -H 'Accept: application/vnd.proxypay.v2+json' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference_id": 904800000,
    "amount": "9701.84"
    }'

POST /payments HTTP/1.1
Authorization: Token reh8inj33o3algd2tpi6tkcnrqf8rjj2
Accept: application/vnd.proxypay.v2+json
Content-Type: application/json

{
  "reference_id": 904800000,
  "amount": "9701.84"
}

<?php
$payment = [
    "reference_id"  => 904800000,
    "amount"        => "9701.84"
];

$data = json_encode($payment);

$curl = curl_init();

$httpHeader = [
    "Authorization: " . "Token " . "reh8inj33o3algd2tpi6tkcnrqf8rjj2",
    "Accept: application/vnd.proxypay.v2+json",
    "Content-Type: application/json",
    "Content-Length: " . strlen($data)
];

$opts = [
    CURLOPT_URL             => "https://api.proxypay.co.ao/payments",
    CURLOPT_CUSTOMREQUEST   => "POST",
    CURLOPT_HTTP_VERSION    => CURL_HTTP_VERSION_1_1,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_TIMEOUT         => 30,
    CURLOPT_HTTPHEADER      => $httpHeader,
    CURLOPT_POSTFIELDS      => $data
];

curl_setopt_array($curl, $opts);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
?>


JSONObject payment = new JSONObject();

payment.put("reference_id", 904800000)
       .put("amount", "9701.84")

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, payment.toString());
Request request = new Request.Builder()
    .url("https://api.proxypay.co.ao/payments")
    .post(body)
    .addHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2")
    .addHeader("Accept", "application/vnd.proxypay.v2+json")
    .addHeader("Content-Type", "application/json")
    .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://api.proxypay.co.ao/payments");

var request = new RestRequest(Method.POST);

request.RequestFormat = DataFormat.Json;

request.AddHeader("Accept", "application/vnd.proxypay.v2+json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Token " + "reh8inj33o3algd2tpi6tkcnrqf8rjj2");

request.AddBody(new {
  reference_id = 904800000,
  amount = "9701.84"
});

IRestResponse response = client.Execute(request);

The call above returns HTTP Status Code 200 if the Mock Payment was successfully created.

HTTP/1.1 200 OK

This is only available on the Sandbox environment and produces a simulated Payment event, as if originated directly from Multicaixa.

This will trigger a call to the Webhook, if configured. Otherwise the Payment will be available through a call to Get Payments.

HTTP Request

POST /payments

Payload

Name	Type	Required	Description
reference_id	integer	true	Reference Id
amount	string	true	The payment amount

Responses

Status	Meaning	Description
200	OK	Payment created
4xx or 5xx	Error	Please check errors list here

Response Schema

Status Code 200

The response structure is described here.

FAQ

Use this section to search for regular questions regarding the usage of this API.

Questions

Why is JSON invalid if an integer begins with 0?

As per RFC4627, section 2.4, numbers with leading zeros are not allowed.