Navigation:

Native Apple Pay API

Information on the Native Apple Pay API.

Overview
Pre-requisites
Order creation flow
Integration steps
Get Support

Overview

The Native Apple Pay API enables you to accept payments from within your iOS applications through Apple Pay (by using your own certificate).

This payment method is available in all merchant and customer countries that support Apple Pay, and with no Merchant Category Code (MCC) restrictions

Supported transaction types:

Card charges
Pre-authorizations
Recurring transactions

Supported Card Schemes:

Visa
MasterCard
American Express
Discover

Pre-requisites

Before utilising these API calls, you will need to complete the pre-requisite steps, below:

Create a merchant identifier on your Apple developer account through here. Please see the ‘Create a merchant identifier’ section of Apple’s documentation
You will need to provide your account manager with your merchant identifier created above, along with your Viva Merchant ID (demo or production) with which you wish to have the merchant identifier associated
Your account manager will then provide you with a certificate signing request file (’.csr’ extension)
The ‘.csr’ file should be uploaded to your Apple developer environment as described in Apple’s documentation (step 5 should be skipped since you will be using the ‘.csr’ file Viva has provided)
You will then need to download the certificate file generated (’.cer’ extension) which you should then send to your account manager
Your account manager will provide confirmation that the certificate is activated and associated with the Viva merchant account you provided in step 2 of this guide, which will allow you to proceed with the API calls below
Use the generated Payment Processing Certificate to enable Apple Pay Capability in Xcode

Order creation flow

Please see a high-level overview of the order creation process, below:

You first need to check if the device supports making payments through Apple Pay and present the Apple Pay button
When the customer clicks the button, you must create a Payment Request which includes the order details. You will need to pass in the PKPaymentRequest the PKMerchantCapability and set it to 3DS (capability3DS) to specify the cryptographic protocol which will be used to encrypt the payment data
The customer is then presented with the Payment Sheet, if they authorize the payment on their device - and if there are no errors - the Payment Token object, which includes the Payment Data variable (UTF-8 serialized JSON dictionary in binary form which includes the encrypted payment data), is created
You must decode the binary data to JSON format
You then need to convert the decoded JSON paymentData variable to a String and make an API call to Viva which includes the paymentData string, the amount, the currency, a reference and a flag indicating that this is an Apple Pay transaction
Finally, you will receive the response and must update the PKAuthorizationResult object based on the response from Viva and inform the customer of the result

Integration steps

Please see below for integration information for both standard payments and pre-authorized payments.

Step 1. Generate a one-time charge token

Please follow the below process to generate a one-time charge token. After this stage, the process differs for Standard payments and Pre-authorized payments.

Example of Apple Pay Payment Token:

{
	"paymentData": {
		"data": "mHngzucjNd8ABLZ+pIENBz8Kr83ttryenhsmrvRS5fB5mcadQaRbD/Ehm7FYXdYrxe3UgNFC9K7YOIph+LQDjkxbARFe/1mLAqmSZHEtzQ+dvLvN7y2FzVgfRPUAZwc+QGNkD+X/4SEUgNW1GYwe/JsBrW2lmZ5eN0wKckKFoO29cTJtuvNNGO3HcjLKIg22CI4gJrttteywywopOQBE0610eZil5QUKRhze0w6eZJaboEZfbr0kdUryqN7PtpeestvH4TL0o5gM2Pg7Nqly3R8E6OUoXg2SBOt6RP+3FSZYHkNlnG9LHI8QdcLBrzKSiKZtQxPckQY9tAKaAWw8CS6N3MFYQZJlp4c+IFJ4ry51hCqho71Mi0tN++Pz9lYMGtI2+q/J10OaA==",
		"signature": "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",
		"header": {
			"publicKeyHash": "22Jf4ZQdEk1iwN/q1GGattabsofaJF02QO4Y8I8E1zE=",
			"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIyy66HBUAIBc4DuRP/T1TUgUK3HhHmH4XN50vTl7xmJzbKSYdMUYltktn4l8/xaAQSdhKLb9gZnbEZx9YtwmHgpsVg==",
			"transactionId": "51ebf640a23960bd0dee56992f2ef99448cc2654b1e0bfa845d28015cfee7ea"
		},
		"version": "EC_v1"
	},
	"paymentMethod": {
		"displayName": "MasterCard 1504",
		"network": "MasterCard",
		"type": "credit"
	},
	"transactionIdentifier": "51EBF640A23960BD0DCA784DF66E7716A2654B1E0BFA845D28015CFEE7EA"
}

Request example:

post /nativecheckout/v2/chargetokens

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/chargetokens \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100,
    "token": "{\"paymentData\":{\"data\………….8015CFEE7EA\"}"      } ) --> in token insert the Apple Pay Payment Token
}'

There is no need to pass the expirationYear, holderName, number, cvc and expirationMonth parameters, as these are already encrypted within the Token (Apple Pay Payment Token).

3DS authentication session will not take place. The user/cardholder has been authenticated within the app.

Response example:

{
    "chargeToken": "ctok_bcGN8Httat34xtEoYkliYgMrc",
    "redirectToACSForm": "null"
}

Step 2. (for Standard payments)

Please follow the below step for standard payments.

Make the actual charge using the one-time charge token

After having successfully completed the ‘Generate a one-time charge token’ step above, make the actual charge using the one-time charge token by calling the nativecheckout/v2/transactions endpoint.

Request example:

post /nativecheckout/v2/transactions

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 100,
  "preauth": false,
  "sourceCode": "[4-digit code of your payment source]",
  "chargeToken": "[charge token]",
  "installments": 1,
  "allowsRecurring": false,
  "merchantTrns": "Merchant transaction reference",
  "customerTrns": "Short description of items/services purchased to display to your customer",
  "currencyCode": 826,
  "customer": {
	  "email": "native@vivawallet.com",
	  "phone": "442036666770",
	  "fullname": "John Smith",
	  "requestLang": "en",
	  "countryCode": "GB"
   }
}'

Response example:

{
  "transactionId": "1549bffb-f82d-4f43-9c07-06666666db2c4",
  "redirectUrl": null
}

Step 2. (for Pre-authorized payments)

Please follow the below steps for pre-authorized payments.

Make the pre-authorization using the one-time charge token

After having successfully completed the ‘Generate a one-time charge token’ step above, make the pre-authorization using the one-time charge token by calling the nativecheckout/v2/transactions endpoint.

Note that "preauth"="true" in the below request example

Request example:

post /nativecheckout/v2/transactions

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 100,
  "preauth": true,
  "sourceCode": "[4-digit code of your payment source]",
  "chargeToken": "[charge token]",
  "installments": 1,
  "allowsRecurring": false,
  "merchantTrns": "Merchant transaction reference",
  "customerTrns": "Short description of items/services purchased to display to your customer",
  "currencyCode": 826,
  "customer": {
	  "email": "native@vivawallet.com",
	  "phone": "442036666770",
	  "fullname": "John Smith",
	  "requestLang": "en",
	  "countryCode": "GB"
   }
}'

Response example:

{
  "transactionId": "1549bffb-f82d-4f43-9c07-06666666db2c4",
  "redirectUrl": null
}

Capture the pre-authorization

To ultimately capture the pre-authorization, please see the below request example.

Request example:

post /nativecheckout/v2/transactions/{preauthTransactionId}

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions/b1a3067c-321b-4ec6-bc9d-06666666db2c4 \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 300,
}'

Response example:

If the actual charge to the cardholder’s card is successful, then you should receive a response similar to the one below:

{
  "transactionId": "1549bffb-f82d-4f43-9c07-0aae45adb2c4",
  "redirectUrl": null
}

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!