NAV Navbar
HTTP Shell PHP Java C#
  • Introduction
  • API Format
  • Endpoints
  • Versioning
  • Authentication
  • Errors
  • Webhooks
  • Resources
  • References
  • Reference Ids
  • Payments
  • 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

    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 POST "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, enconded 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 string 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.