Initiate 3D Payment

The 3D Payment Initiation step causes a card payment to be put into the 3D Secure authentication process provides.

As a result of this call, the API returns the Base64 encoded 3D content is returned. The merchant must decode this content and redirect the end user to the bank's 3D Secure authentication screen.

⚠️ At this step the payment is not yet completed. After the user completes the authentication at the bank 3D Payment Completion (Auth3d) step should be called.

---

Endpoint

POST /v1/Payment/Init3d

---

Headers

Key	Type	Description	Example
x-ClientID	String	Unique identifier for the API client	your-client-id
x-ClientSecret	String	Secret key for the API client	your-secret-key
x-GrantType	String	Type of access token used	client_credentials
x-Scope	String	API scope	pf_write, pf_read
x-Timestamp	String	Request timestamp	2024-12-17T12:34:56Z

---

Request Body

Field	Required	Type	Description	Example
merchantId	✅	Integer	Unique identifier for the merchant	100000000000004
returnUrl	✅	String (URL)	Redirect URL after successful authentication	https://www.example.com/success
failUrl	✅	String (URL)	Redirect URL after failed authentication	https://www.example.com/error
paymentMethod	✅	String	Payment method	CARDPAYMENT
language	✅	String	Transaction language	tr
conversationId	✅	String	Transaction tracking number	MSD2024030500000000115
sign	✅	String	Digital signature for request verification	AAVWY3RZKJVVCEAD8LDQB4K
paymentInstrumentType	✅	String	Type of payment instrument	CARD
cardDetails.cardNo	✅	String	Card number	4508034508034581
cardDetails.expDate	✅	String	Expiration date (MMyy)	1226
cardDetails.cvv	✅	String	Card security code	000
transactionDetails.transactionType	✅	String	Transaction type	SALE
transactionDetails.installmentCount	✅	Integer	Number of installments	1
transactionDetails.amount	✅	Float	Transaction amount	60.00
transactionDetails.currencyCode	✅	Integer	Currency code (ISO 4217)	949
transactionDetails.vftFlag	❌	Boolean	Indicates whether VFT is enabled	false
cardHolderInfo.cardHolderName	✅	String	Cardholder's name	Selim Dil
cardHolderInfo.buyerGsm	✅	String	Buyer's GSM number	55555555
extraParameter.pfSubMerchantId	❌	String	Sub-merchant ID	12345

Response Body

This service Base64 encoded 3D content is returned. The returned data should be decoded and rendered in the user's browser.

Sample Request

POST /v1/Payment/Init3d
Content-Type: application/json
x-ClientID: your-client-id
x-ClientSecret: your-secret-key
x-GrantType: client_credentials
x-Scope: pf_write, pf_read
x-Timestamp: 2024-12-17T12:34:56Z

{
  "merchantId": 100000000000004,
  "returnUrl": "https://www.example.com/success",
  "failUrl": "https://www.example.com/error",
  "paymentMethod": "CARDPAYMENT",
  "language": "tr",
  "conversationId": "MSD2024030500000000115",
  "sign": "AAVWY3RZKJVVCEAD8LDQB4K...",
  "paymentInstrumentType": "CARD",
  "cardDetails": {
    "cardNo": "4508034508034581",
    "expDate": "1226",
    "cvv": "000"
  },
  "transactionDetails": {
    "transactionType": "SALE",
    "installmentCount": 1,
    "amount": 60.00,
    "currencyCode": 949,
    "vftFlag": false
  },
  "cardHolderInfo": {
    "cardHolderName": "Selim Dil",
    "buyerGsm": "55555555"
  },
  "extraParameter": {
    "pfSubMerchantId": "12345"
  }
}

Sample Response

{
  "threeDSecureContent": "PGh0bWw+Li4uPC9odG1sPg=="
}

threeDSecureContent field Should be Base64 decoded and shown to the user.