Transactions

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 WAPPoint's systems. Many of the following requests will go unused if the WAPPoint 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 WAPPoint Hosted Payments Page which is where the customer should be redirected if using the WAPPoint Hosted Payment Page. When using the WAPPoint 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 WAPPoint 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 WAPPoint 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 WAPPoint 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 WAPPoint 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 WAPPoint 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 WAPPoint 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 WAPPoint 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"
    }
}

Suggested knowledgebase articles:

Transactions

Get a single transaction

GET `/v2/transactions/:id/`

Get a list of transactions

GET `/v2/transactions/`

Create a transaction

POST `/v2/transactions/`

Update a transaction

PUT `/v2/transactions/:id`

Refund a transaction

PUT `/v2/transactions/:id/`

Process a transaction

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

Request

Delete a transaction

DELETE `/v2/transactions/:id/`

Request

Associate Customer

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

Request

Associate Service (Lock to Service)

PUT `/v2/transactions/:id`

Article Details

Related articles

Suggested knowledgebase articles:

Transactions

Get a single transaction

GET /v2/transactions/:id/

Get a list of transactions

GET /v2/transactions/

Create a transaction

POST /v2/transactions/

Update a transaction

PUT /v2/transactions/:id

Refund a transaction

PUT /v2/transactions/:id/

Process a transaction

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

Request

Delete a transaction

DELETE /v2/transactions/:id/

Request

Associate Customer

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

Request

Associate Service (Lock to Service)

PUT /v2/transactions/:id

Article Details

Related articles

GET `/v2/transactions/:id/`

GET `/v2/transactions/`

POST `/v2/transactions/`

PUT `/v2/transactions/:id`

PUT `/v2/transactions/:id/`

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

DELETE `/v2/transactions/:id/`

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

PUT `/v2/transactions/:id`