iyzico one-off payment and installment easy payment integration

Transcription

1 iyzico one-off payment and installment easy payment integration Version: iyzi teknoloji ve ödeme sistemleri A.Ş. iyzico one-off payment and installment 1

2 Release History Date Version Reason for Issue 15/06/ Initial Version 27/11/ Support new iyzico API 15/01/ Support installment 25/02/ New Template 15/05/ Add Platform solution support 30/07/ Updated urls and parameters as per new izico checkout 06/08/ Updated requests and response parameters 07/08/ Added error codes and example request 12/08/ Formatting 13/08/ Modified responses, form integration methods and added items group in request, new request parameters 21/08/ Updated error codes 21/08/ Updated document with RG support and new error codes 03/02/ Updated document with CP support iyzico one-off payment and installment 2

3 Preface iyzico one-off payment and installment Copyright 2014 iyzi teknoloji ve ödeme sistemleri A.Ş. - All rights reserved. The information contained in this document is intended only for the person or entity to which it is addressed and contains confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact iyzi teknoloji ve ödeme sistemleri A.Ş. and delete the material from any computer. iyzico one-off payment and installment 3

4 Contents 1. Introduction Generate a token for payment API User Group Transaction Group Payment Group Presentation Group Customer Information Group Address Group Contact Group Platform Group Items Information Group Let the shopper pay - build the payment form What does it mean: URL for redirecting the shopper after the payment? Get the status of the transaction Samples Generate a token for payment Let the shopper pay - build the payment form Capture Error codes General error codes Internal error codes iyzico one-off payment and installment 4

5 1. Introduction The iyzico Integration has two basic layers: 1) Processing of POST requests and responses 2) Transmission of POST parameters The complete iyzico integration specification was designed to be as easily understandable and polymorphic as possible. That means that all payment methods reuse the same tag set and coding scheme with very minor modifications. Thus the integration of an additional payment method just requires changes to the value of the code attribute in the form action by creating the payment form (chapter 3 Let the shopper pay - build the payment form). No further modifications are mandatory. iyzico one-off payment and installment 5

6 2. Generate a token for payment Prepare the payment request with all data that are not meant for the shopper to know or to change. Those data are typically your payment credentials and fixed values such as amount and currency. The preparation call is simply done with a POST request from the merchant's server to the payment server. The JSON response contains a token which you need in the second step for building the payment form. Do a server-to-server call and send POST data to the following URL Live & Test system: Following parameters Groups can be sent to iyzico payment gateway. 2.1 API User Group The User Group contains the authentication information about the Merchants API ID and Secret Key. Parameter Data Type Length Mandatory Description api_id Alpha 32 YES API ID of the sending Merchant. secret Alpha 32 YES secret API key of the Merchant 2.2 Transaction Group The Transaction Group contains all information required to process a transaction. Parameter Data Type Length Mandatory Description mode Alpha 4 YES test Test system for credit cards live Live system transaction_id Alpha 12 No Transaction id of DB or PA transaction. Required on Capture/Refund request external_id Alpha 32 YES Transaction id, must be unique for each request iyzico one-off payment and installment 6

7 2.3 Payment Group The Payment Group determines which payment method and type to use and provides all monetary payment details of the transaction. Parameter Data Type Length Mandatory Description type Alpha 4 YES Transaction type (CC.DB, RG.DB, CC.PA, RG.PA, CC.CP) For normal debit transaction, pass type parameter as CC.DB and: 1. Register card with Debit transaction, pass type parameter as RG.DB and amount greater than Just register a card, pass type parameter as RG.DB and amount 0. For pre-authorization transaction, pass type parameter as CC.PA and: 1. Register card with pre-authorization transaction, pass type parameter as RG.DB and amount greater than Just register a card, pass type parameter as RG.PA and amount 0. For capture transaction request, pass type parameter as CC.CP iyzico one-off payment and installment 7

8 2.4 Presentation Group The presentation groups define the basket of the customer. All parameters within the Presentation Group are mandatory: Parameter Data Type Length Mandatory Description amount # ,2 YES Presentation Amount in currency of the Currency parameter. Do not use dot, (Send 100 for 1.00 TRY) currency Alpha 3 YES Currency code according to the ISO 4217 specification. The complete list of supported currencies: TRY USD EUR GBP customer_presentation_usage Alphanum YES Provides the dynamic part of the descriptor, which appears on the end customer s statement. Enables the end customer to associate the transaction on the statement to the online transaction. return_url Alphanum YES Return url, result page for transaction eric installment Alpha 0..5 No Installment transaction, true or false. 2.5 Customer Information Group To identify the customer you can send the Company name, First and Last name from the customer. iyzico one-off payment and installment 8

9 Parameter Data Type Length Mandatory Description iyzi teknoloji ve ödeme sistemleri A.Ş. customer_name_company Alpha 2 50 NO Company name of the customer customer_first_name Alpha NO First name of the end customer. customer_last_name Alpha NO Last name name of the end customer. customer_language Alpha 2 NO Language, en or tr 2.6 Address Group For Retails payments please sent every time the billing address from the customer. Parameter Data Type Length Mandatory Description customer_shipping_address_line_1 Alphanumeric NO Shipping street and street number of the end customer. customer_shipping_address_line_2 Alphanumeric NO Second shipping address line. customer_shipping_address_zip Alphanumeric NO Shipping ZIP code of the end customer s resivdence. customer_shipping_address_city Alpha NO Shipping City or location where the end customer lives. customer_shipping_address_state Alpha No Shipping State of end customer. customer_shipping_address_country Alpha 2 NO Shipping Country code according to the ISO specification. customer_billing_address_line_1 Alphanumeric NO Billing street and street number of the end customer. customer_billing_address_line_2 Alphanumeric NO Second billing address line. customer_billing_address_zip Alphanumeric NO Billing ZIP code of the end customer s resivdence. customer_billing_address_city Alpha NO Billing City or location where the end customer lives. customer_billing_address_state Alpha No Billing State of end customer customer_billing_address_country Alpha 2 NO Billing Country code according to the ISO specification. iyzico one-off payment and installment 9

10 2.7 Contact Group For security reason please send iyzico the and IP Address from the customer. Parameter Data Type Length Mandatory Description customer_contact_phone Numeric 15 NO Phone number of customer, used for risk management purposes customer_contact_mobile Numeric 15 NO GSM number of customer, used for risk management purposes customer_contact_ Alphanumeric NO Used for risk management purposes and transmission of direct debit mandates. customer_contact_ip Alphanumeric 15 NO IP number of end customer. Used for risk management purposes. 2.8 Platform Group In relation to iyzico platform solution, iyzico provides parameter to identify and distribute. Parameter Data Type Length Mandatory Description platform_merchant_api_id Alpha 32 YES API ID of the platform s Merchant. platform_share_amount Numeric 15 YES Amount which the platform should get. Required if platform_merchant_api_id is present in request. platform_merchant_share_amount Alphanumeric YES Amount for the platforms Merchant. Required if platform_merchant_api_id is present in request. iyzico one-off payment and installment 10

11 2.9 Items Information Group Item group contains the data of the items in the basket of the customer. NOTES: The following example fields are for the first item of the basket, for the 2nd item field names changes to 'item_id_2', 'item_name_2', 'item_unit_quantity_2' and 'item_unit_amount_2'. If you want to add more items just iterate the number char on the end. Parameter Required Type/Length Explanation item_id_1 Alpha/32 Item id on merchant end item_name_1 Alpha/100 Item name item_unit_quantity_1 Numeric/3 How many of this item item_unit_amount_1 Numeric/6 Gross cost iyzico one-off payment and installment 11

12 3. Let the shopper pay - build the payment form The shopper enters your checkout page, and you simply have to integrate only two lines of code into your html page. There are two ways to integrate the payment form: 1. Use the code snippet from the response In generate token response, you will get a code snippet with pre defined form and javascript. Just include that snippet in your html page. For example, if you are using PHP, <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" " <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> </head> <body> <!-- other contents --> <?php echo $response['code_snippet'];?> <!-- other contents --> </body> </html> 2. Load javascript library with the version, mode, installment, language, token parameter and form tag. Live system (One-off payment): Test system (One-off payment): Live system (Installment): Test system (Installment): Put the following form to the place where the shopper should choose between brands: <form class="iyzico-payment-form"></form> iyzico one-off payment and installment 12

13 For security reasons, it is important to host your live payment form on an HTTPS page. This will assure buyers of your identity and prevent some browsers from displaying errors. 3.1 What does it mean: URL for redirecting the shopper after the payment? After the payment is made, the shopper will be redirected to that specified URL (return_url parameter). The content of that URL contains either a script which asks for the status of the payment in order to redirect the shopper again to an error or a success page (see Step 3) or it contains simply a html "Thank you for paying" dialogue. You don't have a redirect url yet? Don't worry, for testing you can take any URL you want (e.g Get the status of the transaction After the payment is made, the shopper will be redirected to the specified URL with the json result added to the URL (&json={json}). The content of that URL contains either a script which asks for the status of the payment in order to redirect the shopper again to an error or success page, or it simply contains a html "Thank you for paying" dialogue Processing Group The processing group contains a summary of the result of the entire processing. The structure of the status and reason codes is hierarchical while the return code is an independent, internal value which is used for very specific return messages. Any merchant side matching should be performed on the processing code or status and reason codes only, but not on the respective messages associated to these statuses. The result derives from the status of the transaction, which means that a transaction which has the status REJECTED or FAILED has the result failed, while all other statuses result in an success. For each status there are one or several reasons. iyzico one-off payment and installment 13

14 Parameter Data Type Length Mandatory Description response[state] Alfa 10 YES failed or success response[error_code] Alfa 32 YES Error code (cc_transaction_reject) response[error_message] Alfa 3 YES In the case of the status REJECTED or FAILED the result is NOK (Not OK). In all other cases the result is ACK (Acknowledge). response[date_time] ###-##-## 20 YES Date and time of the transaction ##:##:## transaction_token Alphanumeric 32 YES Transaction token mode Alphanumeric 4 YES test / live code_snippet String -- YES HTML code with javascript and form tag. transaction[transaction_id] Alphnumeric 32 YES Transaction id transaction[external_id] Alphanumeric 32 YES Unique transaction id transaction[state] Alfa 10 YES Transaction state (paid, pending, ) transaction[amount] #.## 32 YES Clearing amount transaction[currency] Alfa 3 YES Currency in ISO standard (TRY, USD ) account[bin] Numeric 6 YES BIN number of credit card account[brand] Alpha 10 YES Credit card brand (VISA, MASTER,BONUS, CARDFINANS, MAXIMUM ) account[expiry_month] Numeric 2 YES Expiry month of credit card account[expiry_year] Numeric 4 YES Expiry year of credit card account[last_4_digits] Numeric 4 YES Last 4 digits of credit card installment[count] Numeric 2 YES No. of installments installment[amount] #.## 32 YES Clearing amount installment[final_amount] #.## 32 YES Installment amount iyzico one-off payment and installment 14

15 4. Samples 4.1 Generate a token for payment Parameter Required Example Value api_id X im523dc63b6bd6fid1j757vnphiylead secret X im523dc65eaad9askkcea5du304ag2g6 mode X test external_id X qwe type X CC.DB amount X currency X TRY return_url X customer_first_name John customer_last_name Doe customer_contact_ john@doe.com customer_name_company My Company customer_contact_mobile customer_contact_ip Installment true customer_language tr Response: { "transaction_token":"723c0fa5e20aaa11863a78e80a17ba45", "response":{ "state":"success", "message":"payment token generated" }, "code_snippet": "<script src=" 723c0fa5e20aaa11863a78e80a17ba45"></script><form class="iyzico-payment-form"></form>" } iyzico one-off payment and installment 15

16 Sample error response: { } "response": { "state":"failed", "error_code":"invalid_parameter_genrate_token", "error_message":"token generation failed", "date_time":" :38:31" } 4.2 Let the shopper pay - build the payment form 1. Use the code snippet from the response <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" " <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> </head> <body> <!-- other contents --> <?php echo $response['code_snippet'];?> <!-- other contents --> </body> </html> 2. Load javascript library with the version, mode, installment, language, and token parameter. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" " <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> <script src=" mode=test&token= 723c0fa5e20aaa11863a78e80a17ba45"></script> </head> <body> <!-- other contents --> <form class="iyzico-payment-form"></form> iyzico one-off payment and installment 16

17 <!-- other contents --> </body> </html> Response: For single payment { } "response":{ "state":"success", "error_code":0, "error_message":"successful Processing", "date_time":" :29:44" }, "transaction_token":"4da0d804ffde80610c8a10c b8", "mode":"test", "transaction":{ "transaction_id":" ", "external_id":" qwe", "reference_id":"4da0d804ffde80610c8a10c b8", "state":"paid", "amount":"100", "currency":"try" }, "account":{ "bin":"411111", "brand":"visa", "expiry_month":"8", "expiry_year":"2014", "last_4_digits":"1111" } For installment payment response { "response":{ "state":"success", "error_code":0, "error_message":"successful Processing", "date_time":" :29:44" }, "transaction_token":"4da0d804ffde80610c8a10c b8", "mode":"test", "transaction":{ "transaction_id":" ", iyzico one-off payment and installment 17

18 } "external_id":" qwe", "reference_id":"4da0d804ffde80610c8a10c b8", "state":"paid", "amount":"100", "currency":"try" }, "account":{ "bin":"411111", "brand":"visa", "expiry_month":"8", "expiry_year":"2014", "last_4_digits":"1111" } installment :{ count : 2, amount : 100, final_amount : } Sample error response: { } "response": { "date_time": " :46:55", "error_code": " ", "error_message": "Transaction marked as invalid", "state": "failed" } iyzico one-off payment and installment 18

19 4.3 Capture Parameter Required Example Value api_id X im523dc63b6bd6fid1j757vnphiylead secret X im523dc65eaad9askkcea5du304ag2g6 mode X test transaction_id X external_id X qwe type X CC.CP amount X currency X TRY customer_language tr Response: { } "response":{ "state":"success", "date_time":" :49:09" }, "transaction_token":"e c1b0a1d6a25c7e4210f98cd8", "transaction":{ "transaction_id":" ", "external_id":"3873da37940aee72084cb76c8e3ec60f", "reference_id":"", "state":"paid", "amount":"100", "currency":"try" }, "account":{ "bin":"411111", "brand":"visa", "expiry_month":"8", "expiry_year":"2014", "last_4_digits":"1111" "holder":"xyz" } iyzico one-off payment and installment 19

20 Sample error response: { "response":{ "state":"failed", "error_code":" ", "error_message":"transaction id is not valid in case of capture\/refund request. (Invalid PA or DB transaction id)", "date_time":" :49:09" } } iyzico one-off payment and installment 20

21 5. Error codes If communication between the merchant's e-commerce system and the iyzicoapi POST is disturbed or a logical or technical error occurs, the iyzico system generates and sends a response. It contains detailed error messages which facilitate the localisation and eradication of the problem. 5.1 General error codes The most important error codes and their meaning are listed in the following: Code Description Transaction succeeded Transaction pending Transaction canceled by user Bank not supported for Giropay Account not enabled for Giropay e.g. test account Transaction canceled by merchant Transaction declined by authorization system (updated) Transaction cancelled by user (updated) Registration is not confirmed yet Not confirmed by user Request contains no creditcard, bank account number or bank name Invalid creditcard, bank account number or bank name Request contains no cc/bank account holder Transaction declined (invalid holder) Transaction declined (registration canceled externally) Transaction declined (account temporarily not available. Please try again later) not supported by authorization system Currency field is invalid iyzico one-off payment and installment 21

22 Code Description iyzi teknoloji ve ödeme sistemleri A.Ş Identity contains no or invalid identification value Invalid country Invalid reccurence mode Amount field should not be empty Amount format invalid (only two decimals allowed) Amount is too large Non matching reference amount Invalid amount (probably too large) Amount exceeds credit Referenced tx can not be refunded, captured or reversed (already refunded, captured or reversed) Referenced tx can not be reversed (reversal not possible anymore) Referencing transaction does not match Transaction not permitted Transaction in wrong state on aquirer side Duplicate transaction Invalid card Stolen card Card blocked Card lost Restricted card Pick up card Card type is not processed by the authorization center Wrong expiry date Invalid CVV Incorrect personal identification number Limit exceeded For unknown reason iyzico one-off payment and installment 22

23 Code Description Format error Refund on gambling tx not allowed Transaction declined by authorization system Transaction marked as invalid Suspecting manipulation Too many invalid tries Maximum transaction frequency exceeded Merchants limit exceeded Account blocked Invalid currency, not processed by authorization center Invalid configuration data Invalid CVV, amount is reserved on card for a few days UserAccount Number/ID unknown Registration error Creditcard / bank account declined by clearing house AVS Check Failed AVS Check Failed. Amount is reserved on card for a few days! Acquirer/Bank reported timeout on online transfer transaction Family name too long Company name too long Invalid street Invalid zip cc/bank account holder not valid Invalid Payer Authentication in 3DSecure transaction Waiting for confirmation of non-instant payment. Denied for now Invalid city Invalid address (probably invalid syntax) iyzico one-off payment and installment 23

24 Code Description iyzi teknoloji ve ödeme sistemleri A.Ş invalid phone number (has to start with a digit or a "+", at least 7 and max 25 chars long) Invalid IP number Invalid birthdate Given name too long Unsupported Payment Type Invalid Payment Method Unexpected communication error with connector/acquirer Error response from connector/acquirerc Serious error on gateway Invalid transaction flow, the requested function is not applicable for the referenced transaction No response from connector/acquirer [uncertain result] Timeout at connectors/acquirer side Timeout at connectors/acquirer side (try later) User Authentication Failed PARes Validation failed PARes Validation failed - problem with signature Cardholder Not Found - card number provided is not found in the ranges of the issuer Communication Error to VISA/Mastercard Directory Server Technical Error in 3D system Unsupported User Device - Authentication not possible Card not participating/authentication unavailable User not enrolled invalid format for processing by gateway (no reference id) Transaction rejected because merchant not participating in 3DSecure program Connector/acquirer currently down User session timeout Message Sequence Number of Connector out of sync iyzico one-off payment and installment 24

25 Code Description iyzi teknoloji ve ödeme sistemleri A.Ş Bank account has invalid bankcode/name account number combination Payment type invalid Invalid credit card brand duplicate transaction. Please verify that the UUID is unique Invalid Request Message. The request contains structural errors Invalid Request Message. No valid XML. XML must be urlencoded! maybe it contains a not encoded ampersand or something similar Unknown reason, card holder should call the bank Unknown reason, card holder should call PSP support ConnectorTxId1 with the description "Isbank order Id" field size is out of limit. Please check and try again ConnectorTxId2 with the description "Isbank transaction Id" field size is out of limit. Please check and try again ConnectorTxId2 with the description "Isbank transaction Id" must be used only for reversal request Installments value is not valid Invalid merchant credentials Insufficient parameter for reversal Order has a waiting transaction Invalid retry period unit Recurring or futurerequest is not allowed to plan for long term Installment is not allowed for recurring jobs There are multiple transactions in the order that can be voided. Use ConnectorTxId1 to identify the right The Request is not allowed, because of the merchants risk managment settings Duplicate ConnectorTxId1 with the description "Isbank order Id" found Wrong security code D Secure Error No transaction entry found forconnectortxid1 with the description "Garanti order Id" found. iyzico one-off payment and installment 25

26 Code Description iyzi teknoloji ve ödeme sistemleri A.Ş The order contains more than one transaction please specify Card transaction limit for this day is reached Customer ip transaction limit for this day is reached Internal error Wrong MerchantID, reference is mapped to an other MerchantID Card blacklisted Invalid payment data for configured Recurring Transaction Dispatching Type Channel/Merchant is closed (no processing possible) Cannot be settled referenced tx can not be captured (cut off time reached) cannot refund (refund volume exceeded or tx reversed or invalid workflow?) cannot capture (PA value exceeded, PA reverted or invalid workflow?) cannot reverse (already refunded reversed or invalid workflow?) ip blacklisted UNDEFINED CONNECTOR/ACQUIRER ERROR One or more parameters are missing in request External Id was already used Failed to generate the transaction token Request is failed Requested amount and payment amount does not match Requested currency and payment currency does not match Invalid bank id Invalid installment number Invalid installment amount Bank is not enabled for merchant Transaction is invalid or same transaction already exists. iyzico one-off payment and installment 26

27 Code Description Merchant type is invalid Platform merchant is invalid iyzi teknoloji ve ödeme sistemleri A.Ş Platform share amount and merchant platform share amount does not match with requested amount Invalid payment type Invalid platform merchant Merchant account is blocked, terminated or declined API key and secret are invalid Invalid currency Refund amount exceeds original payment amount Partial refund within the same day is not allowed Transaction mode is invalid Transaction id is not valid Capture amount exceeds original payment amount Return url is invalid. 5.2 Internal error codes Code Description Missing element "Transaction" Payment service not given Amount invalid Missing element "MerchantAccount" Missing or invalid response from payment service Missing or invalid transaction mode Missing element "Payment" D did not receive the approval process Parameter dataload is not parseable. iyzico one-off payment and installment 27

28 Code Description Missing element "CreditCardAccount" Missing StoreKey Missing or invalid currency Missing MerchantName Missing Password Missing MerchantId Missing Brand Missing expiry month Missing expiry year Missing or invalid verification Missing credit card number. iyzi teknoloji ve ödeme sistemleri A.Ş Serious error with payment service: <name>, contact support Payment Type: "CD" is not supported for YAPIKREDI Payment type invalid Wrong ReferencedTransaction type Yapi Kredi 3D process was not successful D amount is different to the transaction amount MPI response invalid Token missmatch Missing element "Basket" Invalid Reference Id Invalid Transaction Id Bank details not found for this merchant Missing or invalid OrderId Invalid item name Bank details not found for this merchant OrderId already used iyzico one-off payment and installment 28