Apple Pay - S2S Decoupled Flow Integration

This section provides comprehensive documentation for integrating Apple Pay with PayU's Server-to-Server (S2S) Decoupled Flow using txn_s2s_flow=4. The Decoupled Flow enables asynchronous payment processing where the payment authorization and completion happen in separate stages, providing enhanced control and flexibility for complex payment scenarios.

Implementation Flow

High-Level Flow Steps

Initialize Payment: Create payment session with Apple Pay token
Prepare Request: Build S2S Decoupled Flow request parameters
Generate Hash: Create SHA-512 hash for request authentication
Submit Authorization: Send initial authorization request
Process Response: Handle asynchronous response processing
Verify Status: Confirm payment status via verification APIs
Complete Transaction: Finalize payment based on business logic

Request Parameters

Mandatory Parameters

Parameter	Description	Example
key `mandatory`	`string` PayU merchant key	"gtKFFx"
txnid `mandatory`	`string` Unique transaction ID	"APPLEPAY_DECOUP_1703845200"
amount `mandatory`	`string` Transaction amount	"100.00"
productinfo `mandatory`	`string` Product description	"Apple Pay Decoupled Payment"
firstname `mandatory`	`string` Customer first name	"John"
email `mandatory`	`string` Customer email address	"[email protected]"
mobile `mandatory`	`string` Customer mobile number	"9876543210"
txn_s2s_flow `mandatory`	`string` Set to "4" for decoupled flow	"4"
pg `mandatory`	`string` Payment gateway identifier	"APPLEPAY"
bankcode `mandatory`	`string` Bank/payment method code	"CCAP"
apple_pay_token `mandatory`	`string` JSON stringified Apple Pay token	'{"paymentData":{...}}'
s2s_client_ip `mandatory`	`string` Client IP address	"192.168.1.1"
s2s_device_info `mandatory`	`string` Device information JSON	'{"device_type":"web"}'
hash `mandatory`	`string` SHA-512 request hash	"calculated_hash"
surl `mandatory`	`string` Success URL	"https://yourapp.com/success"
furl `mandatory`	`string` Failure URL	"https://yourapp.com/failure"
lastname `optional`	`string` Customer last name	"Doe"
address1 `optional`	`string` Customer address line 1	"123 Main St"
address2 `optional`	`string` Customer address line 2	"Apt 4B"
city `optional`	`string` Customer city	"Mumbai"
state `optional`	`string` Customer state	"Maharashtra"
country `optional`	`string` Customer country	"India"
zipcode `optional`	`string` Customer postal code	"400001"
udf1 `optional`	`string` User defined field 1	"custom_value_1"
udf2 `optional`	`string` User defined field 2	"custom_value_2"
udf3 `optional`	`string` User defined field 3	"custom_value_3"
udf4 `optional`	`string` User defined field 4	"custom_value_4"
udf5 `optional`	`string` User defined field 5	"custom_value_5"
phone `optional`	`string` Alternative phone number	"9876543211"

Apple Pay Token Structure

{
  "paymentData": {
    "version": "EC_v1",
    "data": "encrypted_payment_data_base64",
    "signature": "payment_signature",
    "header": {
      "ephemeralPublicKey": "ephemeral_public_key",
      "publicKeyHash": "public_key_hash", 
      "transactionId": "apple_transaction_id"
    }
  },
  "paymentMethod": {
    "displayName": "Visa •••• 1234",
    "network": "Visa",
    "type": "debit"
  },
  "transactionIdentifier": "transaction_identifier"
}

Device Info JSON Structure

{
  "device_type": "web",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) WebKit/537.36",
  "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  "language": "en-US",
  "color_depth": 24,
  "screen_height": 1080,
  "screen_width": 1920,
  "time_zone": 330,
  "java_enabled": false,
  "ip_address": "192.168.1.1",
  "platform": "MacIntel"
}

Hash Generation

Request Hash Pattern

For S2S Decoupled Flow (txn_s2s_flow=4), the hash pattern is:

key|txnid|amount|productinfo|firstname|mobile|email|udf1|udf2|udf3|udf4|udf5||salt

Sample Response

Initial S2S Response

The S2S Decoupled Flow returns an initial response indicating the payment has been queued for processing:

{
  "status": "pending",
  "txnid": "APPLEPAY_DECOUP_1703845200_a1b2c3d4",
  "amount": "100.00",
  "productinfo": "Apple Pay Decoupled Payment",
  "firstname": "John",
  "email": "[email protected]",
  "mihpayid": "403993715527623137",
  "mode": "APPLEPAY",
  "bankcode": "CCAP",
  "PG_TYPE": "APPLEPAY-PG",
  "bank_ref_num": "AP123456789",
  "unmappedstatus": "pending",
  "addedon": "2023-12-29 10:30:00",
  "payment_source": "s2sDecoupledFlow",
  "net_amount_debit": "100.00",
  "hash": "response_hash",
  "message": "Payment initiated successfully. Processing asynchronously.",
  "decoupled_flow_id": "DCF_123456789"
}

Success Response (After Processing)

{
  "status": "success",
  "txnid": "APPLEPAY_DECOUP_1703845200_a1b2c3d4",
  "amount": "100.00",
  "productinfo": "Apple Pay Decoupled Payment", 
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "9876543210",
  "mihpayid": "403993715527623137",
  "mode": "APPLEPAY",
  "status": "success",
  "unmappedstatus": "captured",
  "key": "gtKFFx",
  "bankcode": "CCAP",
  "PG_TYPE": "APPLEPAY-PG",
  "bank_ref_num": "AP123456789",
  "bank_ref_no": "AP123456789",
  "cardnum": "XXXXXXXXXXXX1234",
  "card_hash": "card_hash_value",
  "name_on_card": "Apple Pay User",
  "issuing_bank": "HDFC Bank",
  "card_type": "VISA",
  "net_amount_debit": "100.00",
  "discount": "0.00",
  "addedon": "2023-12-29 10:30:00",
  "payment_source": "s2sDecoupledFlow",
  "udf1": "custom_field_1",
  "udf2": "custom_field_2", 
  "udf3": "custom_field_3",
  "udf4": "custom_field_4",
  "udf5": "custom_field_5",
  "field1": "transaction_date",
  "field2": "bank_name",
  "field3": "payment_gateway_name",
  "field4": "card_country",
  "field5": "pg_mid",
  "field6": "eci_value",
  "field7": "payment_gateway_capture_date",
  "field8": "auth_status",
  "field9": "final_capture_amount",
  "hash": "response_hash",
  "error": "No Error",
  "error_Message": "",
  "decoupled_flow_id": "DCF_123456789",
  "processing_time_ms": 2534
}

Failure Response

{
  "status": "failure",
  "txnid": "APPLEPAY_DECOUP_1703845200_a1b2c3d4",
  "amount": "100.00",
  "productinfo": "Apple Pay Decoupled Payment",
  "firstname": "John",
  "email": "[email protected]",
  "mihpayid": "403993715527623137",
  "mode": "APPLEPAY",
  "unmappedstatus": "failed",
  "bankcode": "CCAP",
  "PG_TYPE": "APPLEPAY-PG",
  "bank_ref_num": "",
  "error": "Transaction declined by issuing bank",
  "error_Message": "Insufficient funds",
  "error_code": "E001",
  "hash": "response_hash",
  "addedon": "2023-12-29 10:30:00",
  "payment_source": "s2sDecoupledFlow",
  "decoupled_flow_id": "DCF_123456789"
}

Updated about 2 hours ago