Processing

Please note the parameters required when Zapper is processing the payment, versus when a third party processor is processing the payment.

Process Payment

POST https://api.zapper.com/v1/payments

Make a new payment against the provided code on behalf of the customer.

Headers

Name	Type	Description
Authorization	String	Bearer <Identity Token> The identity token received from the service account login
x-api-key	string	Authentication Key

Request Body

Name	Type	Description
reference	string	Unique reference for the payment.
currencyISOCode	string	Three character ISO 4217 currency code. Required if non-zapper processed payment.
code	string	Base64 encoded Zapper supported code value.
amount	number	Amount to be paid in cents, excluding tip amount.
tipAmount	number	Tip amount in cents.
customer	object	Details of the customer making the payment.
paymentUTCDate	string	Date of the payment request. Format: yyyy-MM-ddTHH:mm:ss.fffZ
paymentMethod	object	Payment Method for the transaction.
orderReference	string	Unique reference for the invoice used during payment. Mandatory if orderReference was required in decode response.

200 Payment status

{
    "reference": "00000000-0000-0000-0000-000000000000",
    "invoiceReference": "00000000-0000-0000-0000-000000000000",
    "invoiceExternalReference": "00000000-0000-0000-0000-000000000000",
    "merchantName": "SyliviaBiller548655",
    "currencyISOCode": "ZAR",
    "invoicedAmount": 1000,
    "paymentReference": "XGKGE3020Q2E8Y4NRD",
    "paymentUTCDate": "2020-10-06T00:00:00.0Z",
    "paymentMethodType": "Card",
    "paymentMethodDescription": "xxxx0002",
    "status": "success",
    "verificationUrl": null,
    "tipAmount": 200,
    "processedAmount": 1200,
    "customer": {
        "id": "00000000-0000-0000-0000-000000000000"
    },
    "siteReference": "1",
	"errors": null
}

302

401 Identity token invalid.

500 Error on the server.

Customer

Field	Type	Description
id	string	Unique identifier for the customer.
countryISOCode	string optional	Customers country. When information is not provided the customer will be created with a default country of ZA. Format: ISO 3166-1 Alpha-2
firstName	string	Customer first name.
lastName	string	Customer last name.
msisdn	string optional	Customer phone number.
email	string optional	Customer email address.

To service our merchants it is recommended that the customer firstName and lastName fields are populated.

These fields assist in allocating and reconciling partner consumer app payments processed over our network.

These details will not and cannot be used for direct marketing given we don’t have the partner consumer app MSISDN.

Payment Method

Field	Type	Description
card	object conditional	Card details.
external	object conditional	Third party payment details.

Only one of card or external can be used. When using a card, Zapper will process the payment from the customer's card.

Either CVV or SecureData is required.

Card

Card number

Field	Type	Description
cardNumber	string	Number on the front of the card.
cvv	string conditional	Security code at the back of the card.
holderName	string	Name on the card.
expiryMonth	number	Month the card expires (1-12).
expiryYear	number	Year the card expires (CCYY).
secureData	object conditional	Authenticate security transaction data.

Tokenised card

Field	Type	Description
token	string	The token that represents the card.
cvv	string conditional	Security code at the back of the card.
secureData	object conditional	Authenticate security transaction data.

Secure Data

Field	Type	Description
enrolled	string	The enrolled status.
paresStatus	string	The PARes status.
eci	string	The relevant ECI indicator.
cavv	string	The Base64 encoded cardholder authentication verification value.
xid	string	The Base64 encoded transaction identifier.
secure3DVersion	string	The 3D Secure version e.g. "2.1.0"
secure3DDirectoryServerTransId	string	Unique identifier for the authenticated transaction assigned by the Directory Server
secure3DAuthenticationType	string	Possible values( not limited) to "01", "02", "03" which correspond to static, dynamic or out-of-band respectively. Must be as generated on completion of the authentication process. indicates the method of authentication used

Enrolled

Value	Description
Y	Yes
N	No
U	Unenrolled

PARes Status

Value	Description
Y	Yes
N	No
U	Unenrolled
A	Anenrolled

External

For non-Zapper processed payments, the external payment method type is be used.

Field	Type	Description
reference	string	Third party payment reference.
status	string	Status of the completed payment. The string is case insensitive.

External Payment Status

Value	Description
success	Successful payment processed.
failed	Failed payment processed.

Example Requests

Card number payment

{
    "reference": "00000000-0000-0000-0000-000000000000",
    "code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
    "amount": 1000,
    "tipAmount": 200,
    "customer": {
        "id": "DEF-456"
    },
    "paymentUTCDate": "0001-01-01T00:00:00.000Z",
    "paymentMethod": {
        "card": {
            "cardNumber": "4000000000000002",
            "cvv": "999",
            "holderName": "Card Holder",
            "expiryMonth": 9,
            "expiryYear": 2030
        }
    },
    "orderReference": "00000000-0000-0000-0000-000000000000"
}

Card number payment using secure data

{
    "reference": "00000000-0000-0000-0000-000000000000",
    "code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
    "amount": 1000,
    "tipAmount": 200,
    "customer": {
        "id": "DEF-456"
    },
    "paymentUTCDate": "0001-01-01T00:00:00.000Z",
    "paymentMethod": {
        "card": {
            "cardNumber": "4000000000000002",
            "holderName": "Card Holder",
            "expiryMonth": 9,
            "expiryYear": 2030,
            "secureData": {
                "enrolled": "Y",
                "paresStatus": "Y",
                "cavv": "Td7wOfSL7kueWouRKPhX883w8ReT",
                "xid": "eY4hCbMdj9FQ0X5CV9iQHt2y82T4",
                "eci": "05",
                "secure3DVersion": "2.1.0",
                "secure3DDirectoryServerTransId": "00000000-0000-0000-0000-000000000000",
                "secure3DAuthenticationType": "03"
            }
        }
    },
    "orderReference": "00000000-0000-0000-0000-000000000000"
}

Tokenised card payment

{
    "reference": "00000000-0000-0000-0000-000000000000",
    "code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
    "amount": 1000,
    "tipAmount": 200,
    "customer": {
        "id": "DEF-456"
    },
    "paymentUTCDate": "0001-01-01T00:00:00.000Z",
    "paymentMethod": {
        "card": {
            "token": "00000000-0000-0000-0000-000000000000",
            "cvv": "999"
        }
    },
    "orderReference": "00000000-0000-0000-0000-000000000000"
}

External (non-Zapper) payment

{
    "reference": "bcf12812-affa-42c9-90c8-db65188ff037",
    "code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
    "amount": 1000,
    "tipAmount": 100,
    "paymentUTCDate": "0001-01-01T00:00:00.000Z",
    "customer": {
        "id": "DEF-456"
    },
    "paymentMethod": {
        "external": {
            "reference": "12345",
            "status": "success"
        }
    }
    "orderReference": "00000000-0000-0000-0000-000000000000"
}

Payment Response

Field	DataType	Description
reference	string	Unique reference of the payment.
invoiceReference	string	Zapper's invoice reference.
invoiceExternalReference	string	Merchant's invoice reference.
merchantName	string	Merchant name.
currencyISOCode	string	The Currency ISO code of the invoice.
invoicedAmount	number	The invoiced amount in cents.
paymentReference	string	Zapper's payment reference (Zapper ID).
paymentUTCDate	string	The date of the payment.
paymentMethodType	string	Payment method type for processing the payment.
paymentMethodDescription	string	The masked value of the payment method.
status	string	The status of the payment.
verificationUrl	string optional	The URL to invoke additional verification when the status is verificationRequired.
tipAmount	number	The tip amount paid by the customer in cents.
processedAmount	number	The amount processed for the request. Including tip.
customer	object	The customer's first and last name.
siteReference	string	The identifier of the point of sale till. This is required for the routing of Zapper payments and invoices.
errors	array optional	List of errors related to the transaction.

Payment Status

Value	Description
processing	The transaction is processing.
success	The transaction completed successfully.
failed	The transaction failed during processing.
verificationRequired	The transaction verification. A URL will be returned in the response.

Customer

Field	Datatype	Required	Description
id	string	Yes	The unique reference for the customer.
firstName	string	Yes	The name of the customer.
lastName	string	Yes	The last name of the customer.

Error

Field	Type	Description
errorReference	string	The error identifier. This value can be quoted when contacting support.
message	string	The message regarding the error.