Changes

Date	Change
2024-11-07	MandateActivated changed to include additional fields for SAP mandates only

Introduction

Welcome to the ProxyPay DDS API!

A direct debit system allows businesses (identified by an unique Creditor Entity Identifier henceforward known as IEC) to automatically withdraw funds from a customer's bank account for recurring payments, such as bills or subscriptions. Customers authorize this arrangement (henceforward known as Mandate), specifying payment amounts and frequency. This ensures timely payments and reduces the need for manual transactions, simplifying financial management for both parties.

This API allows developers to easily integrate with Multicaixa DDS to manage mandates and request payments.

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.

Prerequisites

In order to use this API you need:

To enroll with your bank for the Direct Debit System service and get an IEC in the form of AOXXXXXXXXXX from Multicaixa;
To contract ProxyPay DDS and get an API Key for authentication purposes.

Endpoints

Below you may find the API endpoints in use for existing environments.

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

Authentication

ProxyPay DDS uses API keys to allow access to the API and expects for this keys to be included in all API requests to the server as follows:

Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq

You must replace djg69a7s4m4phurgmh9gf2tb5ikm55bq with assigned API key.

Data types

Type	Values
decimal	A string formatted as "[0-9]+(.[0-9]{2,2})"
isodate	A string formatted as "YYYY-MM-DD"
isodatetime	A string that conforms with ISO8601, example: "YYYY-MM-DDTHH:MI:SSZ"
number	A valid number
object	JSON object
string	One or more of the following characteres [A-Za-z0-9\s\/-\?:().\,\'+]

Resources

Mandates

Register Mandate (CAP)

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/mandates" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 8888888032539, 
    "contract_id": "8999204754", 
    "credit_iban": "AO06005100000000000000003",
    "debit_iban":  "AO06000600000000000000064",
    "debitor_name": "NDALU NGUEVE",
    "email": "email@dominio.com",
    "max_amount": "51000.23",
    "mobile": "+244-912345678",
    "preauth": true, 
    "image_id": "1224c29f32a875bdcddc6977c5c6fc2e5545bba6ee3a0fc05eb3f44038e7c916",
    "signature_date": "2024-08-28",
    "recurrence": "ADHO", 
    "purpose": "TRAD", 
    "tax_id": "000102501LA920",
    "mobile": "+244-912345678"    
  }'

{
  "contract_id":"8999204754",
  "credit_iban":"AO06005100000000000000003",
  "debit_iban":"AO06000600000000000000064",
  "debitor_name":"NDALU NGUEVE",
  "email":"email@dominio.com",
  "final_collection_date":null,
  "first_collection_date":null,
  "id":8888888032539,
  "image_id":"1224c29f32a875bdcddc6977c5c6fc2e5545bba6ee3a0fc05eb3f44038e7c916",
  "max_amount":"51000.23",
  "mobile":"+244-912345678",
  "preauth":true,
  "purpose":"TRAD",
  "recurrence":"ADHO",
  "signature_date":"2024-08-28",
  "tax_id":"000102501LA920"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "contract_id":"8999204754",
  "credit_iban":"AO06005100000000000000003",
  "debit_iban":"AO06000600000000000000064",
  "debitor_name":"NDALU NGUEVE",
  "email":"email@dominio.com",
  "final_collection_date":null,
  "first_collection_date":null,
  "id":8888888032539,
  "image_id":"1224c29f32a875bdcddc6977c5c6fc2e5545bba6ee3a0fc05eb3f44038e7c916",
  "max_amount":"51000.23",
  "mobile":"+244-912345678",
  "preauth":true,
  "purpose":"TRAD",
  "recurrence":"ADHO",
  "signature_date":"2024-08-28",
  "tax_id":"000102501LA920"
}

CAP Mandates are mandates where the user explicitly authorized that the entity charge directly his bank account for the recurring bills. Usually involves signing a document that must conform to a specific structure.

This endpoint submits a CAP mandate registration command for processing.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/mandates

URL Parameters

Parameter	Description
entity_id	IEC

Payload

Parameter	Type	Required	Max Length	Description
contract_id	string	True	35	Associated one-to-one with mandate id
credit_iban	string	True	25	The IBAN where all payments requested for this given mandate will be credited to
debit_iban	string	True	25	The IBAN from which payments will be debited.
debitor_name	string	True	70	Name of the debitor/client
email	string	False	50	Email from the debitor
final_collection_date	isodate	False	-	The final date until which the mandate is valid and payment requests can be sent to the central system.
first_collection_date	isodate	False	-	The initial date from which payments can be sent to the central system
id	number	True	12	The mandate identifier
image_id	string	True	-	The image identifier that is result from image processing jobs.
max_amount	decimal	False	21	Mandate maximum authorized amount formatted with two decimal places "10000.00"
mobile	string	False	14	Formatted in the format +244-XXXXXXXXX for Angolan numbers only
preauth	boolean	True	-	Set to `true`
recurrence	string	True	4	Mandate payment frequency. Refer to Mandate recurrence. Defaults to `ADHO`
signature_date	isodate	True	10	In the form of YYYY-MM-DD. Must match the signature date in the processed image.
tax_id	string	True	14	Tax id of the debitor

Responses

Status	Meaning	Description
201	Created	Register Mandate command submitted successfully
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
contract_id	string	Associated one-to-one with mandate id
credit_iban	string	The IBAN where all payments requested for this given mandate will be credited to
debit_iban	string	The IBAN from which payments will be debited.
debitor_name	string	Name of the debitor/client
email	string	Email from the debitor
final_collection_date	isodate	The final date until which the mandate is valid and payment requests can be sent to the central system.
first_collection_date	isodate	The initial date from which payments can be sent to the central system
id	number	The mandate identifier
image_id	string	The image identifier that is result from image processing jobs.
max_amount	decimal	Mandate maximum authorized amount formatted with two decimal places "10000.00"
mobile	string	Formatted in the format "+244-XXXXXXXXX" for Angolan numbers only
preauth	boolean	Set to `true`
recurrence	string	Mandate payment frequency. Refer to Mandate recurrence
signature_date	isodate	In the form of YYYY-MM-DD. Must match the signature date in the processed image.
tax_id	string	Tax id of the debitor

Register Mandate (SAP)

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/mandates" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -d '{
        "id": 8888888032636, 
        "contract_id": "7888193643", 
        "credit_iban":"AO06005100002286022210163", 
        "preauth": false, 
        "recurrence": "ADHO", 
        "purpose": "TRAD", 
        "debitor_name": "NDALU NGUEVE", 
        "tax_id": "000214613LA032"
    }'

{
  "contract_id": "7888193643",
  "credit_iban": "AO06005100002286022210163",
  "debit_iban": null,
  "debitor_name": "NDALU NGUEVE",
  "email": null,
  "final_collection_date": null,
  "first_collection_date": null,
  "id": 8888888032636,
  "image_id": null,
  "max_amount": null,
  "mobile": null,
  "preauth": false,
  "purpose": "TRAD",
  "recurrence": "ADHO",
  "signature_date": null,
  "tax_id": "000214613LA032"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "contract_id": "7888193643",
  "credit_iban": "AO06005100002286022210163",
  "debit_iban": null,
  "debitor_name": "NDALU NGUEVE",
  "email": null,
  "final_collection_date": null,
  "first_collection_date": null,
  "id": 8888888032636,
  "image_id": null,
  "max_amount": null,
  "mobile": null,
  "preauth": false,
  "purpose": "TRAD",
  "recurrence": "ADHO",
  "signature_date": null,
  "tax_id": "000214613LA032"
}

SAP Mandates are mandates that are only activated when the user, through the accepted interfaces (ATM, Multicaixa Express or Internet Banking) explicitly binds the mandate with his bank account. Doesn't involve signing document.

This endpoint submits a SAP mandate registration command for processing.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/mandates

URL Parameters

Parameter	Description
entity_id	IEC

Payload

Parameter	Type	Required	Max Length	Description
contract_id	string	True	35	Associated one-to-one with mandate id
credit_iban	string	True	25	The IBAN where all payments requested for this given mandate will be credited to
debitor_name	string	True	70	Name of the debitor/client
email	string	False	50	Email from the debitor
final_collection_date	isodate)	False	-	The final date until which the mandate is valid and payment requests can be sent to the central system.
fist_collection_date	isodate	False	-	The initial date from which payments can be sent to the central system
id	number	True	12	The mandate identifier
max_amount	decimal	False	21	Mandate maximum authorized amount formatted with two decimal places "10000.00"
mobile	string	False	14	Formatted in the format +244-XXXXXXXXX for Angolan numbers only
preauth	boolean	True	-	Set to `false`
recurrence	string	True	4	Mandate payment frequency. Refer to Mandate recurrence. Defaults to `ADHO`
tax_id	string	True	14	Tax id of the debitor

Responses

Status	Meaning	Description
201	Created	The Register Mandate command was submitted successfully
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
contract_id	string	Associated one-to-one with mandate id
credit_iban	string	The IBAN where all payments requested for this given mandate will be credited to
debitor_name	string	Name of the debitor/client
email	string	Email from the debitor
final_collection_date	string (ISO8601)	The final date until which the mandate is valid and payment requests can be sent to the central system.
fist_collection_date	string (ISO8601)	The initial date from which payments can be sent to the central system
id	number	The mandate identifier
max_amount	decimal	Mandate maximum authorized amount formatted with two decimal places "10000.00"
mobile	string	Formatted in the format +244-XXXXXXXXX for Angolan numbers only
preauth	boolean	Set to `false`
recurrence	string	Mandate payment frequency. Refer to Mandate recurrence.
tax_id	string	Tax id of the debitor

Cancel Mandate

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/mandates/" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -d '{
        "mandate_id": 8888888031957,
        "reason": "CTAM"
    }'

{
  "mandate_id": 8888888031957,
  "reason": "CTAM"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "mandate_id": 8888888031957,
  "reason": "CTAM"
}

Submits a Mandate cancelation command for processing.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/mandates/{mandate_id}/cancelations

URL Parameters

Parameter	Description
entity_id	IEC
mandate_id	Mandate identifier

Payload

Parameter	Type	Required	Max Length	Description
reason	string	True	4	Mandate cancelation reason. Refer to Mandate Cancelation Reason (By Creditor)

Responses

Status	Meaning	Description
201	Created	The Cancel Mandate command was successfully submitted
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
mandate_id	number	Mandate identifier
reason	string	Mandate cancelation reason. Refer to Mandate Cancelation Reason (By Creditor)

Payments

Present Payment

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/mandates/8888888031666/payments" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -d '{
      "id": 1, 
      "transaction_id": "8888888031666.1", 
      "purpose": "TRAD", 
      "amount": "1111.00", 
      "collection_date": "2024-10-01"
    }'

{
  "amount": "1111.00",
  "collection_date": "2024-10-01",
  "id": 1,
  "mandate_id": 8888888031666,
  "purpose": "TRAD",
  "transaction_id": "8888888031666.1"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "amount": "1111.00",
  "collection_date": "2024-10-01",
  "id": 1,
  "mandate_id": 8888888031666,
  "purpose": "TRAD",
  "transaction_id": "8888888031666.1"
}

Submits a debit instruction for processing.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/mandates/{mandate_id}/payments

URL Parameters

Parameter	Description
entity_id	IEC
mandate_id	Mandate identifier

Payload

Parameter	Type	Required	Max Length	Description
id	number	True	4	Unique unused and sequential payment id for a given mandate
transaction_id	string	True	35	Client side payment ID
amount	decimal	False	21	Decimal number formatted as string (e.g. "123.45").
collection_date	isodate	False	10	Date formatted as "YYYY-MM-DD"
purpose	string	False	4	Mandate / Payment purpose. Refer to Mandate/Payment purpose

Responses

Status	Meaning	Description
201	Created	The Payment Presentation command was submitted successfully
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
amount	decimal	Decimal number formatted as string (e.g. "123.45")
collection_date	isodate	Date formatted as "YYYY-MM-DD"
id	number	Unique unused and sequential payment id for the mandate
mandate_id	number	Mandate identifier
purpose	string	Mandate / Payment purpose. Refer to Mandate/Payment purpose
transaction_id	string	Client side payment ID

Cancel Payment

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/mandates/8888888031666/payments/2/cancelations" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -d '{
      "cancelation_id": "8888888031666.cancel.2", 
      "reason": "CUST"
    }'

{
    "cancelation_id": "8888888031666.2.cancel",
    "mandate_id": 8888888031666,
    "payment_id": 2, 
    "reason": "CUST"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
    "cancelation_id": "8888888031666.2.cancel",
    "mandate_id": 8888888031666,
    "payment_id": 2, 
    "reason": "CUST"
}

Submits a Payment cancelation command for processing. Presented instructions can be canceled before the collection date.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/mandates/{mandate_id}/payments/{payment_id}/cancelations

URL Parameters

Parameter	Description
entity_id	IEC
mandate_id	Mandate identifier to which the payment to be canceled belongs
payment_id	Payment identifier to cancel

Payload

Parameter	Type	Required	Max Length	Description
cancelation_id	string	True	35	Client-side cancelation ID
reason	string	False	4	Refer to Payment Cancelation reason

Responses

Status	Meaning	Description
201	Created	The Cancel Payment command was submitted successfully
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
cancelation_id	string	Client-side cancelation ID
mandate_id	number	Mandate identifier
payment_id	number	Payment identifier
reason	string	Refer to Payment Cancelation reason

Reverse Payment

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/mandates/8888888029435/payments/7/reversals" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -d '{
      "amount": "7777.00",
      "reason": "ADEA",
      "reversal_id": "8888888029435.7.reversal"
    }'

{
  "amount": "7777.00",
  "mandate_id": 8888888029435,
  "payment_id": 7,
  "reason": "ADEA",
  "reversal_id": "8888888029435.7.reversal"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "amount": "7777.00",
  "mandate_id": 8888888029435,
  "payment_id": 7,
  "reason": "ADEA",
  "reversal_id": "8888888029435.7.reversal"
}

Submits a payment reversal command for processing. Only Collected instructions can be reversed.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/mandates/{mandate_id}/payments/{payment_id}/reversals

URL Parameters

Parameter	Description
entity_id	IEC
mandate_id	Mandate identifier
payment_id	Payment identifier

Payload

Parameter	Type	Required	Max Length	Description
amount	decimal	True	21	Amount to reverse from collected payment
reason	string	True	4	Refer to Payment Reversal Reason
reversal_id	string	True	35	Client-side reversal ID

Responses

Status	Meaning	Description
201	Created	The Reverse Payment command was successfully submitted
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
amount	decimal	Reversal amount
mandate_id	number	Mandate identifier
payment_id	number	Payment identifier
reason	string	Refer to Payment Reversal Reason
reversal_id	string	Client-side reversal ID

Utility

Stream events

curl "https://api.proxypay.co.ao/dds/v1/AO5900112233/events?offset=0&count=1000" \
  -H "Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq" \
  -H "Accepts: application/json"

[
  ...,
  {
    "data": {
      ...
    },
    "id": "1z2Io3ylbhapqJU6nAZc9SlpMN3",
    "offset": 2,
    "type": "RegisterMandateCreated"
  }
]

Get up to count events from the event stream starting from offset. This endpoint allows for the application to get all events that cause state changes.

HTTP Request

GET http://api.proxypay.co.ao/dds/v1/{entity_id}/events?offset={offset}&count={count}

URL Parameters

Parameter	Description
entity_id	IEC
offset	The offset from which to get the events. Defaults to `0`
count	Amount of events to fetch. Defaults to `1000`

Responses

Status	Meaning	Description
200	OK	Returns empty list or List of events
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 200

List of events with the following schema:

Attribute	Type	Descrition
data	object	Contains the details for the event
id	string	Event ID
type	string	Event Type
offset	number	Offset that should be used when requesting the list of the new events past this offset

Sequences

curl -X POST "https://api.proxypay.co.ao/dds/v1/AO5900112233/sequences" \
  -H "Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq" \
  -H "Content-Type: application/json" \
  -d '{ "type": "mandate" }'

curl -X POST "https://api.proxypay.co.ao/dds/v1/AO5900112233/sequences" \
  -H "Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq" \
  -H "Content-Type: application/json" \
  -d '{ "type": "payment", "mandate_id": 195 }'

{
  "id": 195
}

{
  "id": 1
}

Get the next identifier in the sequence for a given type:

Mandate identifiers are unique within a given IEC;
Payment identifiers are unique within a given IEC and Mandate.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/sequences

URL Parameters

Parameter	Description
entity_id	N/A

Payload

Parameter	Type	Required	Max Length	Description
type	string	True	7	One of `mandate`or `payment``
mandate_id	number	False	13	One valid mandate identifier. Only required when type is `payment`

Responses

Status	Meaning	Description
200	OK	Sequence created
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 200

Parameter	Type	Description
id	number	When type is `mandate` returns the next unique identifier within `entity_id`. When type is `payment` returns the next unique identifier within `entity_id` and `mandate_id`.

Authorization Form

curl -X POST "https://api.proxypay.co.ao/dds/v1/AO5900112233/authorization_forms" \
  -H "Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq" \
  -H "Content-Type: application/json" \
  -d '{ 
      "id": 8888888032539, 
      "contract_id": "8999204754", 
      "debit_iban": "AO06000600000000000000002", 
      "recurrence": "ADHO", 
      "debitor_name": "NDALU NGUEVE", 
      "tax_id": "000102501LA920", 
      "mobile": "+244-912345678", 
      "email": "email@dominio.com", 
      "max_amount": "51000.23", 
      "signature_date": "2024-09-28"
      }' \
  -o authorization_form.pdf

File authorization_form.pdf was written

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

<<BINARY DATA>>

Generates a PDF form for the given inputs in the correct format that is expected for pre-authorized mandate forms.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/authorization_forms

URL Parameters

Parameter	Description
entity_id	IEC

Payload

Parameter	Type	Required	Max Length	Description
contract_id	string	True	35	Associated one-to-one with mandate id
credit_iban	string	True	25	The IBAN where all payments requested for this given mandate will be credited to
debit_iban	string	True	25	The IBAN from which payments will be debited
debitor_name	string	True	70	Name of the debitor/client
email	string	False	50	Email from the debitor
id	number	True	12	Mandate identifier
max_amount	decimal	False	21	Mandate maximum authorized amount formatted with two decimal places "10000.00"
mobile	string	False	14	Formatted in the format +244-XXXXXXXXX for Angolan numbers only
recurrence	string	True	4	Recurrence
signature_date	isodate	True	10	YYYY-MM-DD
tax_id	string	True	14	Tax id of the debitor

Responses

Status	Meaning	Description
200	OK	Authorization Form created
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 200

The response body corresponds to the PDF binary.

The content of the PDF is produced with the following layout.

PDF Sample

Image Processing (Submit Job)

curl -X POST "https://api.proxypay.ao/dds/v1/AO5900112233/image_processings/" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary "@path_to_file"

{
  "id": "2miLoojDp3iPIImfqLan8OEZZW0",
  "image_id": null,
  "mandate_id": null,
  "status": 1
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "2miLoojDp3iPIImfqLan8OEZZW0",
  "image_id": null,
  "mandate_id": null,
  "status": 1
}

Requests a transformation of the scanned Authorization Form into a grayscale JPEG that can be submitted to the SDD system (via the image_base64 using this command.

The input can be a PDF , JPEG or PNG, in any rotation. The transformation detects the edges using the corner markers to rotate and crop. The QR-Code is read to extract the Mandate ID.

Rotations of any angle are tolerated, but changes in scale (resizing the input) can prevent the marker detection from working correctly.

HTTP Request

POST http://api.proxypay.co.ao/dds/v1/{entity_id}/image_processings

URL Parameters

Parameter	Description
entity_id	IEC

Payload

The binary content of the image to process and convert to Multicaixa format

Responses

Status	Meaning	Description
201	Created	The image processing job was created
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 201

Parameter	Type	Description
id	string	Image processing job identifier
image_id	string	Processed image identifier. Null if image hasn't job hasn't finshed yet or successfully, not null otherwise
mandate_id	number	Expected to be `null`
status	number	Status `1` meaning the job was queue for processing

Image Processing (Get Job Info)

curl -X GET "https://api.proxypay.ao/dds/v1/AO5900112233/image_processings/2mZAbwj9pcQFAe44xxIbxaQmbEg" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json'

{
  "id": "2miLoojDp3iPIImfqLan8OEZZW0",
  "image_id": "1224c29f32a875bdcddc6977c5c6fc2e5545bba6ee3a0fc05eb3f44038e7c916",
  "mandate_id": 8888888032539,
  "status": 0
}

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

{
  "id": "2miLoojDp3iPIImfqLan8OEZZW0",
  "image_id": "1224c29f32a875bdcddc6977c5c6fc2e5545bba6ee3a0fc05eb3f44038e7c916",
  "mandate_id": 195,
  "status": 0
}

Gets the current status of a given job request.

The image_id is set to the resulting output image once the job completes (status=0). The image binary content can then be fetched using the image_id.

HTTP Request

GET http://api.proxypay.co.ao/dds/v1/{entity_id}/image_processings/{job_id}

URL Parameters

Parameter	Description
entity_id	IEC
job_id	The identifier of a image processing job gotten from submitting an image/PDF for processing

Responses

Status	Meaning	Description
200	Ok	The status of the image processing job
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 200

Parameter	Type	Description
id	string	Image processing job identifier
image_id	string	Processed image identifier. Null if image hasn't job hasn't finshed yet or successfully, not null otherwise
mandate_id	number	The read mandate identifier from the image
status	number	If `status` is 1, the job is queued. If `status` is 0 the processing was OK. If `status` is -1 the processing failed.

Image Processing (Get Output Image)

curl -X GET "https://api.proxypay.ao/dds/v1/AO5900112233/images/1224c29f32a875bdcddc6977c5c6fc2e5545bba6ee3a0fc05eb3f44038e7c916" \
  -H 'Authorization: Bearer djg69a7s4m4phurgmh9gf2tb5ikm55bq' \
  -H 'Content-Type: application/json' \
  -o /path/to/file.jpg

File /path/to/file.jpg was written

HTTP/1.1 200 Created
Content-Type: image/jpeg
Content-Length: 35243

<<JPG BINARY DATA>>

Gets the JPG image resulting from the image processing job.

HTTP Request

GET http://api.proxypay.co.ao/dds/v1/{entity_id}/images/{image_id}

URL Parameters

Parameter	Description
entity_id	IEC
image_id	The image identifier that was received after getting info for a particular image processing job and `status` was equal to `0`

Responses

Status	Meaning	Description
200	Ok	Retrieving the image was successful
4xx or 5xx	Error	Please check error list here

Response Schema

Status Code 200

JPG Binary content

The content of the JPG is similar to with the configured Logo and data configured for your entity.

JPG Sample

Model

Mandate Events

RegisterMandateCreated

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
credit_iban	string	True	25
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
debit_iban	string	True	25
debitor_name	string	True	70
email	string	False	50
final_collection_date	isodate	False	10	YYYY-MM-DD
first_collection_date	isodate	True	10	YYYY-MM-DD
image_id	string	False	64	Image binary sha256
mandate_id	number	True	12	195 - 999999999999
purpose	string	True	4	Allowed values here
max_amout	decimal	False	21	"999999999999999999.99"
mobile	string	False	14	"+244-999999999"
preauth	boolean	True	-	`true` \| `false`
recurrence	string	True	4	Refer to table here. Defaults to `ADHO`
signature_date	isodate	False	10	"YYYY-MM-DD"
tax_id	string	N	14

RegisterMandateSubmitted

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999

RegisterMandateRejected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime)	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
reason	string	True	4	Refer to mandate rejection reason

MandateRegistered

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	"YYYY-MM-DDTHH:mm:ssZ"
mandate_id	number	True	12	195 - 999999999999

MandateActivated

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
email	string	False	50	For SAP mandates only
final_collection_date	isodate	False	10	For SAP mandates only
mandate_id	number	True	12	195 - 999999999999
max_amount	decimal	False	21	For SAP mandates only
mobile	string	False	14	For SAP mandates only

MandateChanged

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
email	string	False	50	Set if changed
final_collection_date	isodate	False	10	Set if changed, format "YYYY-MM-DD"
mandate_id	number	True	12	195 - 999999999999
max_amount	decimal	False	21	"123.99"
mobile	string	False	14	Set if changed, format "+244-999999999"
requester	string	True	4	Refer to Mandate Change/Cancelation Requester

MandateRejected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
reason	string	True	4	Refer to mandate rejection reason

CancelMandateCreated

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
reason	string	True	4	Refer to mandate cancelation reason

CancelMandateSubmitted

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
reason	string	True	4	Refer to mandate cancelation reason

CancelMandateRejected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
reason	string	True	4	Refer to mandate cancelation reason

MandateCanceled

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
reason	string	True	4	Refer to mandate cancelation reason
requester	string	True	4	Refer to Mandate Change/Cancelation Requester

Payment Events

PresentPaymentCreated

Attribute	Type	Required	Max. Length	Description
amount	decimal	True	21	"999999999999999999.99"
collection_date	isodatetime	True	10	YYYY-MM-DD
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
purpose	string	True	4	Allowed values here. Must be valid within original mandate purpose.
transaction_id	string	True	35	Client side payment ID

PresentPaymentSubmitted

Attribute	Type	Required	Max. Length	Description
amount	decimal	True	21	"999999999999999999.99"
collection_date	isodate	True	10	Requested to central system
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	"YYYY-MM-DDTHH:mm:ssZ"
mandate_id	number	True	12	195 - 999999999999
original_collection_Date	isodate	True	10	Requested by Entity
payment_id	number	True	4	1 - 9999
purpose	string	True	4	Allowed values here. Must be valid within original mandate purpose.
transaction_id	string	True	35	Client side payment ID

PresentPaymentRejected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
reason	string	True	4	Refer to Payment Rejection Reason
transaction_id	string	True	35	Client side payment ID

PaymentPresented

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID

PaymentCollected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
settlement_date	isodate	True	10	Effective collection date
transaction_id	string	True	35	Client side payment ID

PaymentRejected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
reason	string	True	4	Refer to Payment Rejection Reason
retry	boolean	True	-	`true` means it will be retried automatically
transaction_id	string	True	35	Client side payment ID

PaymentReversed

Attribute	Type	Required	Max. Length	Description
amount	decimal	True	21	The reversed amount
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
reason	string	True	4	Refer to Payment Reversal Reason
reversal_id	string	True	35	Client-side reversal id
transaction_id	string	True	35	Client side payment ID

PaymentRevoked

Attribute	Type	Required	Max. Length	Description
amount	decimal	True	21	The reversed amount
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
reason	string	True	4	Refer to Payment Revocation Reason
revocation_id	string	True	35	Client side revocation ID
transaction_id	string	True	35	Client side payment ID

CancelPaymentCreated

Attribute	Type	Required	Max. Length	Description
cancelation_id	string	True	35	Client side cancelation id
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
reason	string	True	4	Refer to Payment Cancelation Reason
transaction_id	string	True	35	Client side payment ID

CancelPaymentSubmitted

Attribute	Type	Required	Max. Length	Description
cancelation_id	string	True	35	Client side cancelation id
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID

CancelPaymentRejected

Attribute	Type	Required	Max. Length	Description
cancelation_id	string	True	35	Client side cancelation id
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID

PaymentCanceled

Attribute	Type	Required	Max. Length	Description
cancelation_id	string	True	35	Client side cancelation id
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID
reason	string	True	4	Refer to Payment Cancelation Reason

ReversePaymentCreated

Attribute	Type	Required	Max. Length	Description
amount	decimal	True	21	Reversal amount
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID
reason	string	True	4	Refer to Payment Reversal Reason
reversal_id	string	True	35	Client side reversal ID

ReversePaymentSubmitted

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID
reversal_id	string	True	35	Client side reversal ID

ReversePaymentRejected

Attribute	Type	Required	Max. Length	Description
contract_id	string	True	35	Client side mandate ID
datetime	isodatetime	True	10	YYYY-MM-DDTHH:mm:ssZ
mandate_id	number	True	12	195 - 999999999999
payment_id	number	True	4	1 - 9999
transaction_id	string	True	35	Client side payment ID
reversal_id	string	True	35	Client side reversal ID

Lookup Tables

Mandate Recurrence

Describes how frequently a payment can be issued for a mandate. It's enforced by the central system.

Recurrence	Description
ADHO	Ad Hoc
DAIL	Daily
WEEK	Weekly
MNTH	Monthly
QURT	Quarterly
MIAN	Biannually
YEAR	Yearly

Mandate Payment Purpose

Describes the purpose of the mandate and payment. The combination of both classify the nature of the transaction.

Mandate Purpose	Payment Purpose	Description
CASH	RINP	Recurring Installment Payment
CCRD	CCRD	Credit Card Payment
GOVT	GOVT	Government Payment
OTRF	AIRB	Air
OTRF	OTHR	Other
OTRF	FERB	Ferry
OTRF	UTIL	Utilities
OTRF	HSPC	Hospital Care
OTRF	MDCS	Medical Services
SSBE	SSBE	Social Security Benefits
SUPP	MSVC	Multiple Service Type
SUPP	NOWS	Not Otherwise Specified
SUPP	RCPT	Receipt Payment
SUPP	NWCH	Network Charge
SUPP	NWCM	Network Communication
SUPP	OTLC	Other Telecom Related Bill
TAXS	TAXS	Tax Payment
TRAD	CMDT	Commodity Transfer
TRAD	ENRG	Energies
TRAD	GDDS	Purchase Sale Of Goods
TRAD	SCVE	Purchase Sale Of Services
TRAD	TRAD	Trade Services

Mandate Rejection Reason

Reason	Description
AC04	Account closed
AC06	Account blocked
AG01	Transaction not allowed for this type of account
AM02	Amount not authorized
AM05	Duplicate operation
ANCF	Debitor signature does not match
DS02	Mandate canceled
FR01	Rejected for fraud suspicion
MD07	Debitor deceased
MD16	Per debitor instruction
RR05	Debitor name doesn't match

Mandate Cancelation Reason (By Creditor)

Reason	Description
CTAM	Due to changes on contract agreement
CTCA	Due to contract cancelation by debitor
CTEX	Contract expired
CUST	Per debitor request
MCFC	Last debit already charged
MSUC	Number of defined debits exceeded
RFEC	Fraud

Mandate Cancelation Reason (By Debitor or SDD System)

Reason	Description
DEDB	Due to changes on contract agreement
CTCA	Due to contract cancelation by debitor
CTEX	Contract expired
CUST	Per debitor request
MCFC	Last debit already charged
MSUC	Number of defined debits exceeded
RFED	Fraud - By request of debitor
DS24	SDD System - Mandate acceptance time window expired
DS99	SDD System - Mandate inactivity time window expired
DUPL	Duplicated debit

Mandate Change/Cancelation Requester

Requester	Description
CUST	Debitor request at bank counter
RBED	Debitor Bank
RBEC	Creditor Bank
RCEC	Creditor
CSTA	Debitor request at the ATM
CSTH	Debitor request at the internet banking
SYST	System's initiative

Payment Rejection Reason

Reason	Description
AC04	Account closed
AC06	Account blocked
AG01	Transaction not allowed for this type of account
AM02	Amount not authorized
AM04	Insufficient Funds
AM05	Duplicate operation
AM09	Amount different from aggreement amount
AM14	Amount exceeds agreement amount
ANCF	Debitor signature doesn't confer
DS02	Mandate canceled
FR01	Refused/Revoked by fraud suspicion
MD07	Deceased debtor
MD16	As per debitor instruction
MS02	Refused by debitor - Unknown reason
RR05	Debitor name doesn't confer
XM04	Insufficient funds - will be presetend again automatically
ED05	Settlement failed (typically the debitor's bank doesn't have enough funds)

Payment Cancelation Reason

Reason	Description
CTAM	Contract changes
CTCA	Debitor canceled contract
CTEX	Contract expired
CUST	Requested by debitor
MCFC	Last instruction already debited
MSUC	Max returned instructions exceeded
RFEC	Requested by creditor's bank

Payment Revocation Reason

Reason	Description
AM05	Duplicate operation
AM09	Amount different from aggreement amount
AM14	Amount exceeds agreement amount
FR01	Refused/Revoked by fraud suspicion
MD16	As per debitor instruction
MS02	Refused by debitor - Unknown reason

Payment Reversal Reason

Reason	Description
ADEA	Debit occurred after service termination
AM05	Duplicate operation
AM09	Amount different from contracted
DUPL	Duplicate debit
MS02	Refused by debitor
MS03	Refused by debitor's bank

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files...just save them to the includes folder and add them to the top of your index.md's frontmatter. Files are included in the order listed.

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! 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.