In AddPay'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
Universally unique identifier (UUID) per of the customer object.

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:
READY
The contract has been created - default status.
ACTIVE
The contracts transactions are queued waiting for processing.
VALIDATING
The contracts payment instrument (An instrument is the resource that contains account information such as a mandate/bank account or card) is being validated through AddPay's verification services.
COMPLETE
The contract has no more queued transactions, all queued transactions have processed. You may append more transaction which will then mark the contract as ACTIVE again.
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:
MONTH
Sets a monthly interval
WEEK
Sets a weekly interval
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