Wikipay - API Docs

API Reference
API Format
Authentication
Errors
Refereces
1. Get
2. Create
3. Cancel
Payment

curl
Ruby
Python
PHP
Java
Node
Go

Welcome to Wikipay API v1

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 Wikipay 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.

Quick Start:
1. Sign up FREE
2. Get your API key
3. Create an Reference

https://api.wikipay.ao

API Format

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

 Content-Type: application/json

Authentication

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

Authorization: [YOUR_API_KEY]

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

Info! Make sure you keep your API Key a secret!.

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



curl 'https://api.wikipay.ao/v1' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

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

Errors

Erros

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on example's end. (These are rare.)

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

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

HTTP Request
GET https://api.wikipay.ao/v1/reference



curl "https://api.wikipay.ao/v1/reference" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns JSON structured like this:


{
  "references": [
    {
      "status": " Paid",
      "number": "002 000 319",
      "id": "00424002000319",
      "expiry_date": "2021-06-08 23:59:00",
      "custom_fields": {
        "name": "",
        "tel": "",
        "email": "",
        "invoice": ""
      },
      "amount": "666.00"
    },
    {
      "status": " Expired",
      "number": null,
      "id": "1",
      "expiry_date": "2021-06-08 23:59:00",
      "custom_fields": {
        "name": "",
        "tel": "",
        "email": "",
        "invoice": ""
      },
      "amount": "666.98"
    }
  ],
  "meta": {
    "total_count": 10,
    "offset": 0,
    "limit": 20
  }
}

This endpoint retrieves a specific reference.

HTTP Request
GET https://api.wikipay.ao/v1/reference/<ID>



curl "https://api.wikipay.ao/v1/reference/00424002001002" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns JSON structured like this:


{
  "references": [
    {
      "status": " Paid",
      "number": "002 001 002",
      "id": "00424002001002",
      "expiry_date": "2021-06-09 23:59:00",
      "custom_fields": {
        "name": "",
        "tel": "",
        "email": "",
        "invoice": ""
      },
      "amount": "3424.98"
    }
  ],
  "meta": {
    "total_count": 1,
    "offset": 0,
    "limit": 20
  }
}

Creat

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

HTTP Request
POST https://api.wikipay.ao/v1/reference/create

Body Request

Name	Type	Required	Description
`reference`	Object	Required	Invoice data to be created
`amount`	String	Required	he amount to be paid, specified with units and exactly two decimal places, with a . as separator. The amount can be a number up to 99999999.99. All amounts are in AOA (Angolan Kwanza).
`expiry_date`	String	Required	A date in the format YYYY-MM-DD (ISO 8601) and WAT timezone. The reference will be considered valid for payment until the end of the specified day.
`custom_fields`	String	Depends	This is a map with an arbitrary number of keys. All values must be strings. This can hold any information useful to reconcile the payment notification, because the payment event will inherit all the custom_field values. Examples include the invoice number, PO number, customer ID, etc..



curl -XPOST 'https://api.wikipay.ao/v1/reference/create' \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \
  -d '{
"reference": 
{
  "amount": "5.00",
  "expiry_date": "2021-06-16T21:58:00z",
  "custom_fields": {
    "nome": "D",
    "encomenda": "2021/0333",
    "telefone": "1",
    "email": "1"
  }
}
}' \

The above command returns JSON structured like this:


{
  "reference": {
    "amount": "5.00",
    "created_at": "",
    "custom_fields": {
      "nome": "D",
      "encomenda": "2021/0333",
      "telefone": "1",
      "email": "1"
    },
    "entity_id": "00999",
    "expiry_date": "2021-06-16T21:58:00z",
    "id": "A8KFqnMLD0Zn2UpZqK",
    "number": "741 820 581",
    "product_bitmap": 1,
    "status": "",
    "updated_at": ""
  }
}

Cancel Reference

This endpoint deletes a reference with given Id..

HTTP Request
DELETE https://api.wikipay.ao/v1/reference/cancel/<ID>



curl -XDELETE "https://api.wikipay.ao/v1/reference/cancel/4495003526088" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns HTTP Status 204 No Content.

Payment

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):

Get

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

HTTP Request
GET https://api.wikipay.ao/v1/payment

Body result

Info! You must must acknowledge the payment events after processing them.



curl "https://api.wikipay.ao/v1/payment" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns JSON structured like this:


{
  "payments": [
    {
      "terminal_type": "01",
      "terminal_transaction_id": "00123",
      "terminal_location": "Luanda",
      "terminal_id": "00456",
      "reference_number": "000000002001002",
      "reference_id": "8uVigNJ7Jj4hvVMdhQ",
      "id": "449500352608",
      "entity_id": "00424",
      "datetime": "2015-05-10T17:43:10Z",
      "fee": "150",
      "period_id": "1",
      "period_end_datetime": "2015-05-10 20:00:00",
      "custom_fields": {
        "name": "",
        "tel": "",
        "email": "",
        "invoice": ""
      },
      "amount": "5000.09"
    },
    {
      "terminal_type": "01",
      "terminal_transaction_id": "00123",
      "terminal_location": "Luanda",
      "terminal_id": "00456",
      "reference_number": "000000002000319",
      "reference_id": "8uVigNJ7Jj4hvVMdhQ",
      "id": "449500352608",
      "entity_id": "00424",
      "datetime": "2015-05-10T17:43:10Z",
      "fee": "150",
      "period_id": "1",
      "period_end_datetime": "2015-05-10 20:00:00",
      "custom_fields": {
        "name": "",
        "tel": "",
        "email": "",
        "invoice": ""
      },
      "amount": "5000"
    }
  ],
  "meta": {
    "total_count": 2,
    "offset": 0,
    "limit": 20
  }
}

This endpoint retrieves a specific payment.

HTTP Request
GET https://api.wikipay.ao/v1/payment/<ID>



curl "https://api.wikipay.ao/v1/payment/449500352608" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns JSON structured like this:


{
  "payments": [
    {
      "terminal_type": "01",
      "terminal_transaction_id": "00123",
      "terminal_location": "Luanda",
      "terminal_id": "00456",
      "reference_number": "000000002001002",
      "reference_id": "8uVigNJ7Jj4hvVMdhQ",
      "id": "449500352608",
      "entity_id": "00424",
      "datetime": "2015-05-10T17:43:10Z",
      "fee": "150",
      "period_id": "1",
      "period_end_datetime": "2015-05-10 20:00:00",
      "custom_fields": {
        "name": "",
        "tel": "",
        "email": "",
        "invoice": ""
      },
      "amount": "5000.09"
    }
  
}

Acknowledge a Payment

This endpoint acknowledges that a specific payment has been processed..

HTTP Request
DELETE https://api.wikipay.ao/v1/payment/<ID>



curl -XDELETE "https://api.wikipay.ao/v1/payment/4495003526088" \
  -H 'Authorization: sferdfbGE47fb22eZvKYlo2Cc0fo87EHa' \
  -H 'Content-Type: application/json' \

The above command returns HTTP Status 204 No Content.

Create a Mock Payment

building

Webhook

As an alternative to periodically fetching Payment events, wikiPay can instead be configured to send new Payment events via HTTP(S) POST directly to your application.
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 wikiPay 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, wikiPay will continue to retry at increasing intervals. WikiPay 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.

Alternative way for defining webhook

We provide an alternative way to set the desired webhook without having to configure one statically on WikiPay. When creating/updating a reference, a custom field can be used to define the callback url desired to be notified if and when said reference is paid. By default the custom_field is called callback_url.

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))



curl - POST "callback_url" \
  -H 'X-Signature: 33313364666466363834383064373264356230626162646633' \
  -H 'Content-Type: application/json' \
  -d  '{
	"terminal_type": "0",
	"terminal_transaction_id": "00000",
	"terminal_location": "0",
	"terminal_id": "0",
	"reference_number": "109113670",
	"reference_id": "DHC0641724057292",
	"id": "7369344240",
	"entity_id": "00000",
	"datetime": "2024-08-19",
	"fee": "0",
	"period_id": "951",
	"period_end_datetime": "2024-08-19 20:00:00",
	"custom_fields": {
		"name": "007598535OO042",
		"tel": "931999992",
		"email": "ETC",
		"invoice": "10641724057292"
	},
	"amount": "5000"
}'