Contracts
In WAPPoint's context Contracts act as plans and/or agreements between the Merchant and the Customer when performing regular queue of transactions, known as recurring or subscription transactions. A set of rules and constraints are defined to protect the Merchant as well as the Customer from unplanned or unauthorised payments. A Contract is the container that binds several transactions together. It forms a recurring transaction grouping with properties that define what day transactions may occur and what the Contracts status is.
The Contract Object
| Attributes | |||||||||
| id string |
|
||||||||
| reference string |
A unique reference for the contract. Can only contain alphanumeric characters including dashes. | ||||||||
| status string |
The status indicates the processing state of the transaction. The following are the available status keys:
|
||||||||
| error object |
The error object provides a unique code describing the reason for an error. | ||||||||
| error[group] string |
A unique string assigned to the origin gateway of the error code. | ||||||||
| error[code] integer |
A unique per message code that maps to a state message. See the full list of state codes at the end of this document. | ||||||||
| error[message] extended length string |
A human readable description describing the encountered error. | ||||||||
| interval string |
A string defining the frequency that a transaction will be processed on this contract where:
|
||||||||
| action_day integer |
The day of the <interval> value that the transaction will be processed. The interval along with the action_day forms the initiates_at (See Transaction Object) on each transaction queued inside of a contract. If the interval is set to MONTH, the action_day may be between 1 and 31, each transaction will have it's date incremented by a month and the day of the month will be set the defined action_day of the month - similarly, setting an interval of WEEK will act in the same way except the action_day ranges from 1 - 7 where 1 is Monday and 7 is Sunday. Note: In instances where there are less than 31 days in a month, the API will automatically adjust the date to the last day of the respective month. |
||||||||
| display_commence timestamp |
A display commencement date to display on the mandate object to confuse yourself. | ||||||||
| display_duration integer |
A display duration number to display on the mandate for the duration of <interval> to confuse yourself. | ||||||||
| display_recurring decimal |
A display amount to display on the mandate as a recurring amount to confuse yourself. | ||||||||
| mandate object/boolean |
If the customer payment instrument is of type BANK, this will contain the Mandate Object. Returns false if no mandate has been created. | ||||||||
| transactions array |
Returns a list of the queued Transaction Object's in order of processing (action day) date. | ||||||||
| first_transaction_at timestamp/boolean |
The timestamp of the first transaction in the contract's transactions queue. Returns false if there are no transaction attached to the contract. | ||||||||
| current_transaction_at timestamp/boolean |
The transaction next in line for processing's timestamp. Returns false if there are no transaction attached to the contract. | ||||||||
| last_transaction_at timestamp/boolean |
The last (the end of the queue) transactions processing timestamp in the contract's queue. Returns false if there are no transaction attached to the contract. | ||||||||
| created_at timestamp |
Returns a timestamp of creation date of the contract |
Get a contract
GET /v2/contracts/:id/
Request
curl -s \ --header "Content-Type: application/json" \ --header "Authorization: Token :token" \ --request GET "https://secure-test.addpay.co.za/v2/contracts/:id"
Response
{
"meta":{
"status":"success",
"message":"OK",
"code":200
},
"data":{
"id": "00072cf6-722d-49ec-9569-bdf44766f9d3",
"reference": "Sample",
"status": "ACTIVE",
"state": {
"code": "2000",
"message": "Created"
},
"interval": "MONTH",
"action_day": 31,
"transactions": [
{
"id": "03f3e02e-ef55-4843-ad30-5b74295325a9",
"status": "QUEUED",
"state": {
"code": 2000,
"message": ""
},
"intent": "SUBSCRIPTION",
"service": false,
"reference": "Sample",
"description": "Sample",
"amount": {
"value": 1,
"display": "R1.00",
"currency": {
"code": "ZAR",
"name": "South African Rand"
}
},
"initiates_at": "2018-04-30 00:00:00",
"completed_at": false,
"created_at": "2018-04-09 21:40:37"
},
{
"id": "03f3e02e-ef55-4843-ad30-5b74295325a9",
"status": "QUEUED",
"state": {
"code": 2000,
"message": ""
},
"intent": "SUBSCRIPTION",
"service": false,
"reference": "Sample",
"description": "Sample",
"amount": {
"value": 1,
"display": "R1.00",
"currency": {
"code": "ZAR",
"name": "South African Rand"
}
},
"initiates_at": "2018-05-31 00:00:00",
"completed_at": false,
"created_at": "2018-04-09 21:40:37"
},
],
"freeze_at": false,
"unfreeze_at": false,
"created_at": "2018-04-09 21:35:16",
}
}
Get a list of contracts
GET /v2/contracts/
Request
curl -s \ --header "Content-Type: application/json" \ --header "Authorization: Token :token" \ --request GET "https://secure-test.addpay.co.za/v2/contracts/"
Response
{
"meta":{
"status":"success",
"message":"OK",
"code":200,
"pagination":{
"records":5,
"page":1,
"pages":1,
"limit":"10"
}
},
"data":[
]
}
Create a contract
POST /v2/contracts/
Request
echo '{
"description": "Contract 2018",
"interval": "MONTH",
"action_day": "4",
"recovery_fee": "35.00"
}' | curl --header "Authorization: Token :token" \
--header "Content-Type: application/json" \
--request POST "https://secure-test.addpay.co.za/v2/transactions" \
--data @-
Response
{
"meta": {
"status": "success",
"message": "OK",
"code": 200
},
"data": {
}
}
Update a contract
PUT /v2/contracts/:id
Request
echo '{
}' | curl --header "Authorization: Token :token" \
--header "Content-Type: application/json" \
--request PUT "https://secure-test.addpay.co.za/v2/contracts/:id" \
--data @-
Response
{
"meta": {
"status": "success",
"message": "OK",
"code": 200
},
"data": {
}
}
Delete a contract
DELETE /v2/contracts/:id/
Request
curl -s \ --header "Content-Type: application/json" \ --header "Authorization: Token :token" \ --request DELETE "https://secure-test.addpay.co.za/v2/contracts/:id"
Associate Transaction to Contract
PUT /v2/contracts/:id/transactions/:id
Request
curl -s \ --header "Content-Type: application/json" \ --header "Authorization: Token :token" \ --request PUT https://secure-test.addpay.co.za/v2/contracts/:id/transaction/:id
Dissociate Transaction from Contract
DELETE /v2/contracts/:id/transactions/:id
Request
curl -s \ --header "Content-Type: application/json" \ --header "Authorization: Token :token" \ --request DELETE https://secure-test.addpay.co.za/v2/contracts/:id/transaction/:id