Processing

Please note the parameters required when Zapper is processing the payment, versus when a third party processor is processing the payment.
post
https://api.zapper.com
/v1/payments
Process Payment
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.

Last modified 1mo ago

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.

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

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.

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.