Apple™ Pay - Paythru Developer Documentation¶

1.0 Introduction¶

Paythru can decrypt Apple Pay card tokens and allow a merchant to process payments for iOS applications. Apple Pay on the web support is still being developed and will be added soon.

The overall process for conducting transactions using Apple Pay is:

The customer, on the merchant's app or website, opts to pay using Apple Pay
The merchant initiates the process directly with Apple, using paythru as your payment gateway and your gatewayMerchantId as supplied by Paythru during boarding
Apple will return to the merchant the encrypted card data
The merchant base64 encodes the encrypted card data prior to sending to Paythru
The merchant forwards this base64 encoded payload to the walletPay method of the Paythru Gateway API for decryption and payment processing

1.1 Card Acceptance¶

Paythru can accept cards of any type (e.g. Credit, Debit, PrePaid), scheme (e.g. Visa, MasterCard, American Express) or territory which is supported by the connected acquirer.

2.0 Configuration¶

The developer instructions from Apple are available on their online documentation. You can choose to use Apple Pay with Paythru's Apple Pay certificate or with your own Apple Pay certificate.

2.1 Using Paythru's Apple Pay certificate¶

If you do not already have one, create an Apple Developer account
Create a merchant identifier to enable your app to use Apple Pay, if you do not already have one
From your Paythru Partner portal, download the Apple Pay certificate signing request (CSR)
Submit the CSR to Apple to create a Payment Processing Certificate. Follow the instructions from Apple, skipping the step of creating the CSR.
Implement Apple Pay in your iOS app, following the guidance on Offering Apple Pay in Your App.
Implement our walletPay method, sending in the encrypted payment token, base64 encoded.

2.2 Using your own Apple Pay certificate¶

If you do not already have one, create an Apple Developer account
Create a merchant identifier to enable your app to use Apple Pay, if you do not already have one
Create a Payment Processing certificate. Following the instructions from Apple.
Upload the Payment Processing certificate private key to your Paythru Partner portal.
Implement Apple Pay in your iOS app, following the guidance on Offering Apple Pay in Your App.
Implement our walletPay method, sending in the encrypted payment token, base64 encoded.

3.0 Methods¶

3.1 Wallet Pay method¶

Description¶

The wallet pay method is used to request payment on behalf of a customer using a Google or Apple card token.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned. Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes.

See the Gateway API documentation for detailed descriptions of endpoint URLs, signing requests, error responses and additional parameters.

Note that the payload parameter needs the encrypted card data received from Google or Apple to be base64 encoded prior to transmission.

URL¶

/v3/transaction/walletPay

Request parameters¶

Name	Description	Format
apiKey*	The API Key provided by Paythru used for authentication.	Alpha-numeric characters
apiPassword*	The API Password provided by Paythru used for authentication.	Alpha-numeric characters
payload*	The `paymentData` section of the payload received from Apple Pay, base64 encoded	Base64 encoded string
walletType*	The type of digital wallet being used (Google or Apple)	enum (`googlePay` or `applePay`)
threeDSecure	Defaults to 0 If set to 1 and Apple payload contains PAN only without authentication details then the response would contain an authentication URL. This URL should be set as the 'src' parameter of a new window or iframe and presented to the customer to complete authentication. Merchants will need to discuss setup with Paythru to allow this.	0/1
returnUrl	Required if `threeDSecure` is set 1. The user will be returned to this URL after the authentication has been completed.	URL
paymentType*	The type of payment to be processed	enum (`auth`, `preauth` or `verifycard`)
shaSignature*	The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature	128 Alpha numeric characters
terminalKey	The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional.	Alpha numeric characters
itemName0*	The name of the 1st item. For additional items, please use itemName1, itemName2 etc.	Up to 64 alpha numeric characters
itemPrice0*	The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only.	Integer
itemQuantity0	The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1	Integer
itemReference0	The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional.	Up to 255 characters
currency	The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru.	3 alpha characters
merchantCustomerReference	A reference for the merchant to identify the customer. This parameter is optional and can be used for validating the card key	Up to 45 characters
merchantReference	The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional.	Up to 32 characters
uniqueMerchantReference	A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected.	Up to 128 characters
ipAddress	IP address of the customer	x.x.x.x
Additional fields for MCC 6012 merchants.
mccAccountIdentifier	Customer's account number or reference	Alpha numeric
mccSurname	Customer's surname	Alpha characters
mccPostcode	Customer's Postcode	Alpha numeric characters
mccDateOfBirth	Customer's date of birth	Numeric characters in the format YYYYMMDD

* denotes a mandatory field

Response parameters¶

Name	Description	Format
transactionStatusCode	The status code of the transaction	3 numeric characters
transactionStatus	The human readable status of the transaction	Up to 100 characters
transactionType	The human readable type of the transaction	Up to 100 characters
transactionKey	The unique reference for the transaction generated by Paythru.	32 alpha numeric characters
bank*	Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to): bankAuthCode (Card issuer's authorisation code) bankTransId (Transaction ID issued by acquiring bank) bankResponseCode (Transaction status code issued by acquiring bank) bankResponseMessage (Transaction status message issued by acquiring bank) * bankOrderId (Order ID issued by acquiring bank)	Alpha numeric characters and symbols

Example Requests¶

HTTP Request¶

apiKey=******************
&apiPassword=******************
&payload=ey...Q==
&walletType=googlePay
&terminalKey=default
&currency=GBP
&itemName0=Baseball Cap
&itemPrice0=500
&shaSignature=c007437ec538a5e09b460a70dd7cfb1b7de83dcec5199dd098e37fc92f8929bbd1402a7251acfd1e6e7dc46eb8cd49a1fced21fb4dcc674464a1183d451ac92e
&paymentType=auth

Example Responses¶

HTTP Response (XML)¶

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
    <transactionStatusCode>600</transactionStatusCode>
    <transactionStatus>Approved</transactionStatus>
    <transactionType>TokenisedWalletAuth</transactionType>
    <transactionKey>f2085db4024085b4ffc79cbeca463909</transactionKey>
    <bankTransId>10676</bankTransId>
    <bankResponseCode>1</bankResponseCode>
    <bankResponseMessage>OK</bankResponseMessage>
    <bankAuthCode>20200</bankAuthCode>
</paythruResponse>

HTTP Response (JSON)¶

{
    "transactionStatusCode": 600,
    "transactionStatus": "Approved",
    "transactionType": "TokenisedWalletAuth",
    "transactionKey": "0d39485ae87d7d4ce24561e99316c7b3",
    "bankTransId": "51894",
    "bankResponseCode": "1",
    "bankResponseMessage": "OK",
    "bankAuthCode": "20200"
}