Transactions are the starting point in preparing a payment. They are the containers that hold information about a particular payment, collection or refund between a third-party payment processor and AddPay's systems. Many of the following requests will go unused if the AddPay hosted payment solution is being implemented, however in instances where the merchant requires recurring transactions (scheduled payments), the full scale API must be implemented and all cases must be covered. 


Attributes

id
string
Universally unique identifier (UUID) per transaction.
direct
string
The direct attribute contains a URL to the AddPay Hosted Payments Page which is where the customer should be redirected if using the AddPay Hosted Payment Page. When using the AddPay Hosted Payment Page, the only remaining step after redirecting the customer is parsing the result of the transaction which can be done via Events or a simple GET on the transaction, see below.
redirect
string/boolean
Whenever present [and the AddPay Hosted Payments Page is not being utilized], the customer must be redirected to this URL to complete third-party validation. Returns false when not required.
intent
string
Refers to the type of transaction being prepared. See the Service Object for more information.
reference
string
A unique reference for the transaction. Can only contain alphanumeric characters including dashes.
account_number
string
An account reference (merchant reference generally used for bookkeeping) for the transaction. Can only contain alphanumeric characters including dashes.
description
extended length string
A custom description for the transaction. This is a friendly display description displayed to the customer. Can be a string length of up to 128 characters.
status
string
The status indicates the processing state of the transaction. The following are the available status keys:
READY
The transaction has been created - default status.
FAILED
The transaction processing failed.
REVERSED
The transaction has been reversed.
QUEUED
The transaction is queued for processing. Only applicable to recurring transactions.
PROCESSING
The transaction is being processed. Only applicable to recurring transactions.
COMPLETE
The transaction has been processed.
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.
service
object/boolean
Returns the Service Object. Returns false if the transaction is not service locked.
customer
object/boolean
Returns the Customer Object. Returns false if the transaction does not contain a customer association.
amount
object
The amount object that contains information about the initial transaction collection amount.
amount[value]
decimal
The amount of the initial transaction. Must be in decimal format.
amount[display]
string
A pretty-formatted display label for the transaction amount, returns a comma separated decimal prefixed with the currency's symbol.
amount[currency]
object
Information on the return amount currency
amount[currency][code]
string
The ISO 3166-1 alpha-3 currency code of the transaction amount currency.
amount[currency][name]
string
The human readable display name of the country code ISO.
return_url
string/boolean
The return URL is the URL set by the merchant on the Merchant Console or via the API that tells the AddPay Hosted Payment Page as well as third-party validators where to redirect the customer after the customer has processed or opted out of the transaction process. The URL must be a valid FQDN. The transaction ID query parameter will be automatically appended to the provided url as transaction_id. Returns false if it has not been set.
notify_url
string/boolean
The notify URL is the URL set by the merchant on the Merchant Console or via the API that tells the AddPay system where to fire event notifications. An even is fired for each transaction status change. The URL must be a valid FQDN. The transaction ID query parameter will be automatically appended to the provided url as transaction_id. Returns false if it has not been set.
initiates_at
timestamp/boolean
Only relevant to recurring transactions. This is the date on which the transaction will be processed, attempting to process a transaction before it's initiates_at timestamp will be declined. Returns false if this is not set.
completed_at
timestamp/boolean
The timestamp at which the transaction was successfully processed. Returns false if the transaction has not been processed.
created_at
timestamp/boolean
The timestamp at which the transaction container was provisioned.


Get a single transaction

GET /v2/transactions/:id/


Request

curl -s \
--header "Content-Type: application/json" \
--header "Authorization: Token :token" \
--request GET https://secure-test.addpay.co.za/v2/transactions/:id

Response

{
    "meta": {
        "status": "success",
        "message": "OK",
        "code": 200
    },
    "data": {
        "id": "f14c4a01-0dbd-49b4-a699-5abf3ab15d57",
        "direct": "http://secure-test.addpay.co.za/pay/4NWL",
        "status": "READY",
        "state": {
            "code": 2000,
            "message": ""
        },
        "intent": "SALE",
        "service": false,
        "redirect": false,
        "reference": "Sample",
        "description": "Sample",
        "amount": {
            "value": "1.00",
            "display": "R1.00",
            "currency": {
                "code": "ZAR",
                "name": "South African Rand"
            }
        },
        "customer": false,
        "contract": false,
        "initiates_at": false,
        "completed_at": false,
        "created_at": "2018-04-09 23:36:01"
    }
}


Get a list of transactions

GET /v2/transactions/


Request

curl -s \
--header "Content-Type: application/json" \
--header "Authorization: Token :token" \
--request GET https://secure-test.addpay.co.za/v2/transactions/

Response

{
    "meta": {
        "status": "success",
        "message": "OK",
        "code": 200,
        "pagination": {
            "records": 76,
            "page": 1,
            "pages": 16,
            "limit": "5"
        }
    },
    "data": [
        {
            "id": "03f3e02e-ef55-4843-ad30-5b74295325a9",
            "status": "READY",
            "state": {
                "code": 2000,
                "message": ""
            },
            "intent": "SALE",
            "service": false,
            "reference": "Sample",
            "description": "Sample",
            "amount": {
                "value": 1,
                "display": "R1.00",
                "currency": {
                    "code": "ZAR",
                    "name": "South African Rand"
                }
            },
            "initiates_at": false,
            "completed_at": false,
            "created_at": "2018-04-09 21:40:37"
        },
        {
            "id": "046415f8-9933-49f0-bf66-641f8d5eb149",
            "status": "2000",
            "state": {
                "code": null,
                "message": ""
            },
            "intent": "SALE",
            "service": false,
            "reference": "Sample",
            "description": "Sample",
            "amount": {
                "value": 1,
                "display": "R1.00",
                "currency": {
                    "code": "ZAR",
                    "name": "South African Rand"
                }
            },
            "initiates_at": false,
            "completed_at": false,
            "created_at": "2018-04-09 21:15:21"
        },
        {
            "id": "12425e6d-e45a-43ef-9d75-eb42fc7251a3",
            "status": "READY",
            "state": {
                "code": 2000,
                "message": ""
            },
            "intent": "SALE",
            "service": false,
            "reference": "Sample",
            "description": "Sample",
            "amount": {
                "value": 1,
                "display": "R1.00",
                "currency": {
                    "code": "ZAR",
                    "name": "South African Rand"
                }
            },
            "initiates_at": false,
            "completed_at": false,
            "created_at": "2018-04-09 21:15:07"
        },
        {
            "id": "152648ec-b070-429e-95b3-0fe81356c03b",
            "status": "READY",
            "state": {
                "code": 2000,
                "message": ""
            },
            "intent": "SALE",
            "service": false,
            "reference": "Sample",
            "description": "Sample",
            "amount": {
                "value": 1,
                "display": "R1.00",
                "currency": {
                    "code": "ZAR",
                    "name": "South African Rand"
                }
            },
            "initiates_at": false,
            "completed_at": false,
            "created_at": "2018-04-09 21:40:39"
        },
        {
            "id": "17b100c9-d58b-48a1-a2ac-3c853957e951",
            "status": "READY",
            "state": {
                "code": 2000,
                "message": ""
            },
            "intent": "SALE",
            "service": false,
            "reference": "Sample",
            "description": "Sample",
            "amount": {
                "value": 1,
                "display": "R1.00",
                "currency": {
                    "code": "ZAR",
                    "name": "South African Rand"
                }
            },
            "initiates_at": false,
            "completed_at": false,
            "created_at": "2018-04-09 21:14:17"
        }
    ]
}

 


Create a transaction

POST /v2/transactions/


The first step in creating a transaction is preparing an empty container which will have its dependencies associated thereafter.


Required Params

reference
string
A custom reference for the transaction - should be unique per transaction, but is not enforced. Can only contain alphanumeric characters including dashes.
description
extended length string
A custom description for the transaction. This is a friendly display description displayed to the customer. Can be a string length of up to 128 characters.
amount
object
The amount object that contains information about the initial transaction collection amount.
amount[value]
decimal
The amount of the initial transaction. Must be in decimal format.
amount[currency_code]
string
The ISO 3166-1 alpha-3 currency code of the transaction amount currency.
Optional Params

return_url
string/boolean
The return URL is the URL set by the merchant on the Merchant Console or via the API that tells the AddPay Hosted Payment Page as well as third-party validators where to redirect the customer after the customer has processed or opted out of the transaction process. The URL must be a valid FQDN. The transaction ID query parameter will be automatically appended to the provided url as transaction_id. Returns false if it has not been set.
notify_url
string/boolean
The notify URL is the URL set by the merchant on the Merchant Console or via the API that tells the AddPay system where to fire event notifications. An even is fired for each transaction status change. The URL must be a valid FQDN. The transaction ID query parameter will be automatically appended to the provided url as transaction_id. Returns false if it has not been set.
initiates_at
timestamp/boolean
Only relevant to recurring transactions. This is the date on which the transaction will be processed, attempting to process a transaction before it's initiates_at timestamp will be declined. Returns false if this is not set.

Request

echo '{ 
    "reference": "20180101", 
    "description": "Sample Transaction 2018-01-01", 
     "amount": { 
         "value": 1337.33, 
         "currency_code": "ZAR" 
     } 
}' | 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": {
        "id": "6d0b4c5d-fc61-4934-8ef8-4b1c36656720",
        "direct": "http://secure-test.addpay.co.za/pay/8RXN",
        "status": "READY",
        "state": {
            "code": 2000,
            "message": ""
        },
        "service": false,
        "redirect": false,
        "reference": "Sample",
        "description": "Sample",
        "amount": {
            "value": "1337.33",
            "display": "R1,337.33",
            "currency": {
                "code": "ZAR",
                "name": "South African Rand"
            }
        },
        "customer": false,
        "contract": false,
        "initiates_at": false,
        "completed_at": false,
        "created_at": "2018-04-09 23:49:17"
    }
}


Update a transaction

PUT /v2/transactions/:id



Transactions may require updates in some scenarios to suite your business needs, the AddPay Web API allows this under certain conditions:

  • The transaction has not been processed
  • The transaction is not in a processing state


Optional Params

reference
string
A custom reference for the transaction - should be unique per transaction, but is not enforced. Can only contain alphanumeric characters including dashes.
description
extended length string
A custom description for the transaction. This is a friendly display description displayed to the customer. Can be a string length of up to 128 characters.
intent
string
Refers to the type of transaction being prepared. See the Service Object for more information.
amount
object
The amount object that contains information about the initial transaction collection amount.
amount[value]
decimal
The amount of the initial transaction. Must be in decimal format.
amount[currency_code]
string
The ISO 3166-1 alpha-3 currency code of the transaction amount currency.


Request

echo '{ 
    "description": "New Description 2018-01-01", 
     "amount": { 
         "value": 500.05 
     } 
}' | curl --header "Authorization: Token :token" \
          --header "Content-Type: application/json" \
          --request PUT https://secure-test.addpay.co.za/v2/transactions/:id \
          --data @-


Response

{
    "meta": {
        "status": "success",
        "message": "OK",
        "code": 200
    },
    "data": {
        "id": "f14c4a01-0dbd-49b4-a699-5abf3ab15d57",
        "direct": "http://secure-test.addpay.co.za/pay/4NWL",
        "status": "READY",
        "state": {
            "code": 2000,
            "message": ""
        },
        "service": false,
        "redirect": false,
        "reference": "Sample",
        "description": "New Description 2018-01-01",
        "amount": {
            "value": "500.05",
            "display": "R500.05",
            "currency": {
                "code": "ZAR",
                "name": "South African Rand"
            }
        },
        "customer": false,
        "contract": false,
        "initiates_at": false,
        "completed_at": false,
        "created_at": "2018-04-09 23:36:01"
    }
}

Refund a transaction

PUT /v2/transactions/:id/



Transactions may require to be refunded in some scenarios to suite your business needs, the AddPay Web API allows this under certain conditions:

  • The transaction is completed.
  •  The refund amount is smaller or equal to the initial transaction amount.
  • A refund is only allowed within the first 6 months after the initial transaction date for card transactions.
  • A refund is only allowed within the first 40 days after the initial transaction date for debit order transactions.
  • Our Refund service is only available for Card and Debit Order transactions.


Optional Params

reference
string
A custom reference for the transaction - should be unique per transaction, but is not enforced. Can only contain alphanumeric characters including dashes.
description
extended length string
A custom description for the transaction. This is a friendly display description displayed to the customer. Can be a string length of up to 128 characters.
intent
string
Refers to the type of transaction being prepared. See the Service Object for more information.
amount
object
The amount object that contains information about the initial transaction collection amount.
amount[value]
decimal
The amount of the initial transaction. Must be in decimal format.
amount[currency_code]
string
The ISO 3166-1 alpha-3 currency code of the transaction amount currency.


Request

echo '{ 
    "description": "New Description 2018-01-01",
    "intent": "REFUND", 
    "amount": { 
         "value": 500.05,
         "currency_code": "ZAR",
     } 
}' | curl --header "Authorization: Token :token" \
          --header "Content-Type: application/json" \
          --request PUT https://secure-test.addpay.co.za/v2/transactions/:id \
          --data @-


Response

{
    "meta": {
        "status": "success",
        "message": "OK",
        "code": 200
    },
    "data": {
        "id": "f14c4a01-0dbd-49b4-a699-5abf3ab15d57",
        "direct": "http://secure-test.addpay.co.za/pay/4NWL",
        "status": "REFUNDREADY",
        "state": {
            "code": 2000,
            "message": ""
        },
        "service": false,
        "redirect": false,
        "reference": "Sample",
        "description": "New Description 2018-01-01",
        "amount": {
            "value": "500.05",
            "display": "R500.05",
            "currency": {
                "code": "ZAR",
                "name": "South African Rand"
            }
        },
        "customer": false,
        "contract": false,
        "initiates_at": false,
        "completed_at": false,
        "created_at": "2018-04-09 23:36:01"
    }
}

Process a transaction

PATCH /v2/transactions/:id/services/:key


Request
curl -s \
--header "Content-Type: application/json" \
--header "Authorization: Token :token" \
--request PATCH https://secure-test.addpay.co.za/v2/transactions/:id/services/key


Delete a transaction

DELETE /v2/transactions/:id/


Request
curl -s \
--header "Content-Type: application/json" \
--header "Authorization: Token :token" \
--request DELETE https://secure-test.addpay.co.za/v2/transactions/:id


Associate Customer

PUT /v2/transactions/:id/customers/:id


Request
curl -s \
--header "Content-Type: application/json" \
--header "Authorization: Token :token" \
--request PUT https://secure-test.addpay.co.za/v2/transactions/:id/customers/:id


Associate Service (Lock to Service)

PUT /v2/transactions/:id


Request

echo '{ 
   "service": { 
       "key": "DEBORDER" 
   }' | curl --header "Authorization: Token :token" \
          --header "Content-Type: application/json" \
          --request PUT https://secure-test.addpay.co.za/v2/transactions/:id \
          --data @-


Response

{
    "meta": {
        "status": "success",
        "message": "OK",
        "code": 200
    },
    "data": {
        "id": "f14c4a01-0dbd-49b4-a699-5abf3ab15d57",
        "direct": "http://secure-test.addpay.co.za/pay/4NWL",
        "status": "READY",
        "state": {
            "code": 2000,
            "message": ""
        },
        "service": {,
            "key": "DEBORDER",
            "label": "Mandated Debit Order Service",
            "icon": "https://placeholderimage.com/",
        },
        "redirect": false,
        "reference": "Sample",
        "description": "New Description 2018-01-01",
        "amount": {
            "value": "500.05",
            "display": "R500.05",
            "currency": {
                "code": "ZAR",
                "name": "South African Rand"
            }
        },
        "customer": false,
        "contract": false,
        "initiates_at": false,
        "completed_at": false,
        "created_at": "2018-04-09 23:36:01"
    }
}