The Pay Function /paycc
The pay function captures the payment by processing the provided credit card and order info. The pay function responds with JSON structured data that contains the result of the payment process. The response data will contain the payment transaction when the processing is completed successfully. Otherwise, data will contain an error message to display to customers. The response data may contain a URL address (response.data.tds_url) to redirect the client in the case of issuer bank requests for a 3D secure validation.
The Pay Flow (non-3D secure cases)
Pay Request Parameters
| Parameter | Type / Length | Description | Mand- atory | Sample | Default |
| amount | double(14,2) | Amount of total payment to capture. | YES | 183.56 | |
| merchant_order_ref | string(16) | Unique ID of the order that was given by the merchant. Alphanumeric only: Numbers & A-Z,a-z Letters. The merchant_order_ref value can be used in retrieving transactions. Assigning the order-id or the cart-id of your software will be good practice instead of a random id or date. | YES | A1234567890abcdA | |
| return_url | string(400) URL(https) | Return URL address of the merchant order page. In case of a 3D Secure validation, the client will be redirected to this URL within the result data. return_url must be a HTTPS address with SSL encryption. | YES | https://eticsoft.com/samplepayment/3dsvalidte | |
| client_ip | string(50) | Public IPv4 address of current visitor. This is for the visitor (buyer) IP address, not your web store’s static IP. | YES | 127.0.0.1 | |
| client_firstname | string(100) | Customer/buyer/client given name | YES | John | |
| client_lastname | string(100) | Customer/buyer/client last name | YES | Doe | |
| client_email | string(100) | Customer/buyer/client email address | YES | john@eticsoft.com | |
| client_phone | string(100) | Customer/buyer/client phone number. It is recommended to be in E.164 international standard structure as +CC MMMMMMMMM | YES | +90 2422415985 | |
| currency | string(3) | ISO-4217 standard currency code of order | YES | USD | TRY |
| language | string(2) | ISO-639-1 language code of client | YES | en | tr |
| payment_method | string(100) | The payment method name | YES | creditcard | creditcard |
| number | string(18) | The number of the payment card | YES | 1111222233334444 | |
| holder | string(60) | The holder name of the payment card | YES | John Doe | |
| expire_year | int(4) | The year of the card expire date | YES | 2027 | |
| expire_month | int(2) | The month of the card expire date | YES | 12 | |
| cvv | string(4) | The CVV/CCV code of the payment card | YES | 123 | |
| installment | int(2) | The number of the instalments | YES | 12 | 1 |
Pay & Request Examples
A.) Successful Request & Response Example
Request
{
"head": {
"lang": "tr",
"auth_type": "key",
"publickey": "PublicKey_SkIwa0xpbmF0OWxtM05qQmFZU3Y3NDZvZndFZWttdEVreG0rc2R0Ym1Xdz0",
"random": 805864,
"hash": "fe4b3950c5d27b8e1a54328eaa54e0e5530dc1f909e7b6dc54ad874bb7ab479f",
"date": "2021-09-05 12:49:30"
},
"data": {
"amount": 183.56,
"currency": "TRY",
"language": "tr",
"client_ip": "105.99.3.5",
"payment_method": "creditcard",
"merchant_order_ref": 1630846170,
"return_url": "https://dev.eticsoft.net/eticvpos/v1-0/3dv.php",
"client_firstname": "John",
"client_lastname": "DOE",
"client_email": "john@domain.com",
"client_phone": "05550000000",
"creditcard": {
"number": "4355084355084358",
"holder": "John DOE",
"expire_year": 2026,
"expire_month": 11,
"cvv": "000",
"installment": 2
}
}
}Response
{
"header": {
"result_code": 1,
"result_message": "İşlem Başarılı",
"result_details": "",
"rand": 608366,
"date": "2021-09-05 12:49:35",
"hash": "e61f6d1dde82d7602f8bf887fdb583e7c6a4c90af65a2835936df06842de55c1"
},
"data": {
"merchant_order_reference": "EKBS_12_0000001630846170",
"transaction_id": "1215"
}
}
B) Payment failed case
Request
{
"head": {
"lang": "en",
"auth_type": "key",
"publickey": "PublicKey_SkIwa0xpbmF0OWxtM05qQmFZU3Y3NDZvZndFZWttdEVreG0rc2R0Ym1Xdz0",
"random": 609293,
"hash": "a58253b815990cc0b7d93083a83242126e4e96bed59290f1c328537624729e99",
"date": "2021-09-05 13:17:58"
},
"data": {
"amount": 183.56,
"currency": "TRY",
"language": "tr",
"client_ip": "105.99.3.5",
"payment_method": "creditcard",
"merchant_order_ref": 1630846170,
"return_url": "https://dev.eticsoft.net/eticvpos/v1-0/3dv.php",
"client_firstname": "Jane",
"client_lastname": "DOE”,
"client_email": "jane@domain.com",
"client_phone": "05550000000",
"creditcard": {
"number": "THIS IS NOT A VALID CC NO",
"holder": "Jane DOE",
"expire_year": 2026,
"expire_month": 11,
"cvv": "000",
"installment": 2
}
}
}Response
{
"data": [],
"header": {
"result_code": 1177,
"result_message": "The Creditcard number (data.creditcard.number) can not be validated.",
"result_details": "",
"rand": 621677,
"date": "2021-09-05 13:18:00",
"hash": "2202a9b14a9186c1caa6eeb80ff949da2c7494e23f1fc956b2601ae216c232a6"
},
}
C.) 3D Secure required case
Request
{
"head": {
"lang": "en",
"auth_type": "key",
"publickey": "PublicKey_SkIwa0xpbmF0OWxtM05qQmFZU3Y3NDZvZndFZWttdEVreG0rc2R0Ym1Xdz0",
"random": 877335,
"hash": "649346c4788eef6ca5ebfc7844c15afbeca0ee1113ffae7721d3cd4673ad1cae",
"date": "2021-09-05 13:53:01"
},
"data": {
"amount": 183.56,
"currency": "TRY",
"language": "tr",
"client_ip": "95.10.3.5",
"payment_method": "creditcard",
"merchant_order_ref": 1630849981,
"return_url": "https://dev.eticsoft.net/eticvpos/v1-0/3dv.php",
"client_firstname": "Johnny",
"client_lastname": "DOE",
"client_email": "johnny@domain.com",
"client_phone": "+105000000011",
"creditcard": {
"number": "4355084355084358",
"holder": "Johnny Doe",
"expire_year": 2026,
"expire_month": 11,
"cvv": "000",
"installment": 2
}
}
}Response
{
"data": {
"tds_url": "https://dev.eticsoft.net/eticvpos/process/?bouncetopf=OHdzTTkwalNOZHlUZzFtRUs2a0JkVFVMWHdSV0tyNGF3SDZpeDNSRTFKVEJQbWtBUWZrS0N0cWdJd2NkY094aFpTZjFqdHZ5T3VNZTNYczZXVFIxV1VtaW41dEpkZlFFSUtBL1NxRDBVTTg2dnFrL2lhNVU3WE5aQVFWRmp1Rk5RK0N6MHMrczZNL2Zjb3ZkMTgxV0VpYjZLaGQ4amtyK042UWM1NFZxYkEyUHcyZWNHeE9JSzNTREhtOHBVRmJ3Rm1QQmJ3SU1wMk5sK1dwZkZYbXRWZz09"
},
"header": {
"result_code": 80,
"result_message": "Redirecting to 3D Secure",
"result_details": "",
"rand": 825045,
"date": "2021-09-05 13:54:22",
"hash": "b33ab44676142a8a3bcf18e94941c86d426efda4507bf995c679b265385acb5f"
},
| Success Response{ “header”: { “result_code”: 1, “result_message”: “İşlem Başarılı”, “result_details”: “”, “rand”: 608366, “date”: “2021-09-05 12:49:35”, “hash”: “e61f6d1dde82d7602f8bf887fdb583e7c6a4c90af65a2835936df06842de55c1” }, “data”: { “merchant_order_reference”: “EKBS_12_0000001630846170”, “transaction_id”: “1215” } } | |
| Simple Request (With wrong card number){ “head”: { “lang”: “tr”, “auth_type”: “key”, “publickey”: “PublicKey_SkIwa0xpbmF0OWxtM05qQmFZU3Y3NDZvZndFZWttdEVreG0rc2R0Ym1Xdz0”, “random”: 609293, “hash”: “a58253b815990cc0b7d93083a83242126e4e96bed59290f1c328537624729e99”, “date”: “2021-09-05 13:17:58” }, “data”: { “amount”: 183.56, “currency”: “TRY”, “language”: “tr”, “client_ip”: “105.99.3.5”, “payment_method”: “creditcard”, “merchant_order_ref”: 1630846170, “return_url”: “https://dev.eticsoft.net/eticvpos/v1-0/3dv.php”, “client_firstname”: “Jane”, “client_lastname”: “DOE”, “client_email”: “jane@domain.com”, “client_phone”: “05550000000”, “creditcard”: { “number”: “THIS IS NOT A VALID CC NO”, “holder”: “Jane DOE”, “expire_year”: 2026, “expire_month”: 11, “cvv”: “000”, “installment”: 2 } } } | Fail Response{ “data”: [], “header”: { “result_code”: 1177, “result_message”: “Kredi kartı numarası (data.creditcard.number) doğrulanamadı.”, “result_details”: “”, “rand”: 621677, “date”: “2021-09-05 13:18:00”, “hash”: “2202a9b14a9186c1caa6eeb80ff949da2c7494e23f1fc956b2601ae216c232a6” }, “debug”: “” } |
| Simple Request (with CC that requires 3D secure Validation) { “head”: { “lang”: “tr”, “auth_type”: “key”, “publickey”: “PublicKey_SkIwa0xpbmF0OWxtM05qQmFZU3Y3NDZvZndFZWttdEVreG0rc2R0Ym1Xdz0”, “random”: 877335, “hash”: “649346c4788eef6ca5ebfc7844c15afbeca0ee1113ffae7721d3cd4673ad1cae”, “date”: “2021-09-05 13:53:01” }, “data”: { “amount”: 183.56, “currency”: “TRY”, “language”: “tr”, “client_ip”: “95.10.3.5”, “payment_method”: “creditcard”, “merchant_order_ref”: 1630849981, “return_url”: “https://dev.eticsoft.net/eticvpos/v1-0/3dv.php”, “client_firstname”: “Johnny”, “client_lastname”: “DOE”, “client_email”: “johnny@domain.com”, “client_phone”: “+105000000011”, “creditcard”: { “number”: “4355084355084358”, “holder”: “Johnny Doe”, “expire_year”: 2026, “expire_month”: 11, “cvv”: “000”, “installment”: 2 } } } | Response (Contains 3D Secure redirect link){ “data”: { “tds_url”: “https://dev.eticsoft.net/eticvpos/process/?bouncetopf=OHdzTTkwalNOZHlUZzFtRUs2a0JkVFVMWHdSV0tyNGF3SDZpeDNSRTFKVEJQbWtBUWZrS0N0cWdJd2NkY094aFpTZjFqdHZ5T3VNZTNYczZXVFIxV1VtaW41dEpkZlFFSUtBL1NxRDBVTTg2dnFrL2lhNVU3WE5aQVFWRmp1Rk5RK0N6MHMrczZNL2Zjb3ZkMTgxV0VpYjZLaGQ4amtyK042UWM1NFZxYkEyUHcyZWNHeE9JSzNTREhtOHBVRmJ3Rm1QQmJ3SU1wMk5sK1dwZkZYbXRWZz09” }, “header”: { “result_code”: 80, “result_message”: “3D Yönlendiriliyor”, “result_details”: “”, “rand”: 825045, “date”: “2021-09-05 13:54:22”, “hash”: “b33ab44676142a8a3bcf18e94941c86d426efda4507bf995c679b265385acb5f” }, } |