• Introduction

    This documentation contains the information needed to integrate the merchant's website with the payment gateway Espago using current new API version 3.0.

    There are 3 main options for integration with Espago payment gateway:

    Integration type Description Details
    Payment form or iFrame placed on Seller website Form placed using script Espago iFrame or Espago JS, and making all operation about payments using API request from Seller's system. this documantation
    Redirecting customer from Seller's website to Espago Secure Page Redirect customer with the appropriate parameters about payment to Espago SecureWebsite, and later receiving request from Espago and returning client. [details]
    Integration Seller's website with Przelewy24 Espago/Elavon card payments can be or one of the payment method (or the only one) visible for customer. [details]

    Test shop showing example payment integration: https://warzywko.espago.com/

    Access to test environment https://sandbox.espago.com is granted by Espago Technical Support Team, support @ espago.com.

    • General description of the gateway

      1. Almost all operations related to payment management (payment, getting status, refund, etc) are made using requests to the API (Application Programming Interface). This documentation is mostly focused to the description of the API.
      2. An application architecture is compatible with REST standard.
      3. Reponces to API requests (mainly GET and POST) are returned in JSON format.
      4. The needed encoding for sending data is UTF-8.
        • You should validate the integration of giving as name / surname of the cardholder, eg.:
          • sébasti, takác, grün, žižk - foreign characters with diacritics,
          • zażółć gęślą jaźń - for Polish letters.
      5. In all integration method sensitive card data is sent directly from customer website/device to Espago gateway, bypassing the Seller's appliaction. It dumps from the Seller the responsibility for storing or processing card data, and PCI-DSS certification is limited to completing the questionnaire after signing the contract with Elavon.
      6. Espago provides two scripts in JavaScript, for creating iFrame window and for use in a form. Thanks to the use of the script, payment form can be embedded inside your web site in such a way, that your customer does not leave your website at any time and data cards avoid your server. For websites, where payment form is on seller website, the use this script is mandatory.
      7. In order to ensure an adequate level of security it is preferred the use of SSL (HTTPS) certificate in Seller's website.
      8. Merchant having a number of services (for different currencies and/or different web services) may use tokens and client profiles created in one service also in the rest of his services.
      9. The suggested timeout for API payment request (maximum waiting time for a response from Espago) is 30 seconds, but the vast majority of payments is processed in less than 2 seconds.
      10. It is recommended to avoid triggering cyclical tasks between 3:30 and 5:30 CEST (01:30- 03:30 UTC) on business days; planned servicing work in the Espago infrastructure can be carried out on these dates.
      • Example of a single payment

        Example of a single payment, when payment form is placed on Merchant website:
        1. Filling the form with card details by the client.
        2. Initial validation of the parameters and creating a token with card data (implemented by JS script, token in the form of "cc_xxxxxxxxxx") and sending token_id to merchant's webapplication as form.
        3. Sending a payment request (request to /api/charges) from merchant's service to Espago gateway relying on token recived from the client, and getting responce with confirmation/reason of rejection of the transaction.
        4. If 3-D Secure is available, client must be redirected to the url address, which is sent in the response for the payment request. When client finish 3DS verification, merchant's service recieve back request from Espago (confirmation of transaction) and client is redirected to merchant website.

        Example of a single payment with redirection to Espago secure page:
        1. Sending form (made by customer) from Seller's website to Espago gateway. Form contain information about payments (amount, description, URL for redirecting back, etc)
        2. Customer goes through payment process on Espago website.
        3. Redirecting customer back to Seller's website with information about payment status. Simultaneously sending from Espago to Seller's website request with information about payment status.
      • Information visible to the customer

        Information that are visible to the customer:
        1. If the client's profile has e-mail address, client receive notification e-mail each time he is charged (successfully or not). Notification contains information such as: company trade name, payment description, amount and state. This is the only one situation in which the service Espago sent any information directly to the customer.
        2. After payment, the client sees on his bank account information about payment consisting of the abbreviated name of the company or service, the city and the country's, for example: "EXAMPLE.COM LTD WARSAW PL" - so there is no information about the payment ID or payment description.
        Card information composed of the last 4 digits of the card holder's name and expiry date of the card (ie the data returned in the confirmation of the creation of a client or payments), as defined in the PCI-DSS (standard issued by Visa and MasterCard) are not sensitive data, so the seller has the possibility of storing and displaying it for the customers. For reasons of image you should consider displaying only part of this information, eg. only the last 4 digits of the card, and put the information that you do not store the data set of cards.
    • Integration

      1. The integration process consists of two stages:
        • Integration with test environment (described in this document)
        • Change 5 connection parameters to the corresponding parameters in production environment (parameters require a chage: the address of the gateway, application ID, API password, public_key and parameter "live" in the constructor Espago in payment form).
      2. Go to the second and also the final stage of integration must be preceded by tests merchant's webapplication in the test environment (made by the customer/merchant's developers) and the overall verification of webapplication and validation of the correctness of the implementation form of payment (made by the Support Team Espago).
      3. A list of technical and substantive requirements is available in the "Downloads" section.
      4. Webpanel with the ability to view and set parameters and viewing the test payments, queries and responces is available at https://sandbox.espago.com
      5. Features which should be tested during the integration include:
        • the creation of tokens,
        • charging cards/makng payments,
        • displaying to customer information about reject reason, when payment is not successful,
        • obtain information about payments status,
        • Reversal and refunding of the transaction (no need to implement these features at the beginning, but very useful to test curl queries),
        • The creation of customer profiles and manage them (if there is business need, for example in recurring or in stores where the customer returns and purchases can be repeated)
        • The creation of plans and subscriptions (if there is business need, for example Need to cyclic charges that are automatically invoked by the gateway Espago).
        • recieving back-requests
      6. After integrating to the production environment, test environment still remains available to the Merchant.
      7. At the request of the Seller Support Team Espago can:
        • Add a new service within the Seller's account (eg. For any other currency)
        • Enable / disable the ability to create and use plans and subscriptions (disabled by default).
        • Enable / disable 3D-Secure (enabled by default) or DCC (disabled by default)
        • Create a new user with access to the panel.
        • Provide answers and help solving problems associated with integration.
      8. At download there are available sample files accelerating integration.
    • Compatibility and restrictions

      The purpose of the API is to not limiting in any way the technology used by merchant's services, in which payments are to be integrated, as well as devices from which customers will make payments. Nevertheless, there are some requirements during communication with Espago gateway, and it results in some limitation of compatibility with older technologies:

      • Espago gateway require connections using TLSv1.1 or TLSv1.2 with strong ssl ciphers.

        Starting from 13 February 2018 production gateway Espago accept only encrypted connections using protocols TLSv1.2 or TLSv1.1 (previous also TLSv1 - currently disabled). The current configuration (requirement to use only protocols TLSv1.2 and TLSv1.1) was introduced in the test gateway https://sandbox.espago.com of November 2015, if your system works with sandbox, will work also with production gateway.

        • Some olders systems, libraries or browsers doesn't support this connections, and need to by upgraded.
        • This requirement applies to connections to API, redirections 3D-Secure and access to WWW panel.
        • Detailed description is available in changelog: changes-in-ssl-https-requirements

        List of software that supports TLS 1.2 and TLSv1.1

        System/ application/ library The minimum compatible version Additional notes
        Windows 7 and later In Windows XP and Vista customer need to use alternative web browser (ie. Chrome, Firefox, Opera)
        Windows Server 2008 R2 and later Windows 2008 R2 requires enabling TLSv1.2 in systems registry and enabling additional ssl ciphers
        Android 4.4.4 Android API level 20. Partial support available also in 4.2
        OpenSSL 1.0.1 and later Note: OpenSSL 0.9.8 (all subversion) does not support TLSv1.2
        Apache 2,2,23 and later  
        Java 8 Note: Java 6 and Java 7 does not support TLSv1.2
        .NET Framework 4.5.1 and later enabling in preferences may be needed, and it requires system Windows that supports TLSv1.2

        List of protocols and ssl ciphers alowing secure connection to Espago gateway

        Protokół Dostępne zestawy szyfrów Uwagi

        TLSv1.2

        TLSv1.1

        ECDHE-ECDSA-AES128-GCM-SHA256
        ECDHE-ECDSA-AES256-GCM-SHA384
        ECDHE-RSA-AES256-GCM-SHA384
        ECDHE-RSA-AES128-GCM-SHA256
        kEDH+AESGCM
        ECDHE-ECDSA-AES256-SHA384
        ECDHE-ECDSA-AES256-SHA
        ECDHE-ECDSA-AES128-SHA256
        ECDHE-ECDSA-AES128-SHA
        ECDHE-RSA-AES256-SHA384
        ECDHE-RSA-AES256-SHA
        ECDHE-RSA-AES128-SHA256
        ECDHE-RSA-AES128-SHA
        DHE-RSA-AES256-SHA256
        DHE-DSS-AES256-SHA
        DHE-RSA-AES256-SHA
        DHE-RSA-AES128-SHA256
        DHE-RSA-AES128-SHA
        DHE-DSS-AES128-SHA256
        DHE-RSA-AES128-GCM-SHA256
        DHE-DSS-AES128-GCM-SHA256
        AES256-GCM-SHA384
        AES256-SHA

         

        It is recommended to configure the application to permit connections using the safest available protocols and ciphers, and to have the opportunity to connect with several sets of codes (ie. not forcing one specific one cipher).

        • Testing connections using TLSv1.2 and TLSv1.1

          We added new domain to test gateway, to make debugging/testing easier. 

          • In a test environment we have added alternative domain (giving access to the same server Sandbox) to facilitate testing:
            • https://oldssl-sandbox.espago.com meets the older, phased requirements. This allows testing of payments, despite not meeting the new requirements on SSL.
            • https://sandbox.espago.com meets the current requirements for SSL (the same or even stroner than on production).
            • If your application connect to sandbox.espago.com without problem, it means that after switching to production environment/gateway it will connect to the production gateway Espago without problems, no changes associated with SSL/TLS are required.
          • In case of doubt with connections, please contact our support with information about IP and APP id (ms_xxxxxxx) of your application. We are able to tell you what protocol and cipher is currently using your application during connection with Espago.
      • Payment form doesn't work in Internet Explorer 9 and olders

        Payment form does not work correctly in Internet Explorer Version IE9 and older. Should be used Internet Explorer in version 10 and later, or other browser can be used (Chrome, Firefox, Opera, Safari, etc). There are also problems with creating tokens using Microsoft Edge, due to limitation of CORS support in this browser.

        • The indicated IE browser incompatibility applies to any version of IE in Windows XP, so it is recommended for Windows XP users to make payments using any other browser.
        • The indicated incompatibility is important for example for a program written in .NET on Windows XP, using the built-in system of IE or imitating it in an version earlier than or equal to IE9.
        • Explanation: Script https://js.espago.com/espago-1.2.js that must be implemented in the form of payment uses XMLHttpRequest addressed to a domain other than the seller (request to the gateway Espago forming a token), this is a Cross-Origin Resource Sharing, in short CORS. Older versions of IE do not allow such requests.
    • Headers of Requests

      Communication with an application is performed using HTTP headers. Particular headers are listed in the table below:

      Header Obligatory Content
      Authorization* Required Basic app_id:password
      Accept Required application/vnd.espago.v3+json
      • Authorization* with APP_ID and password come from section "Initial steps" concerns all requests to API excepts creating tokens.
      • Request about creating token (/api/tokens) is authenticated using Public Key and in most cases is done by Espago JS.
      • A series of failed login attempts result in a temporary lock the account.
    • Initial steps

      Please do these steps before sending first request:

      1. Choose Alt text option.
      2. Edit Service using Alt text button.
      3. Fill in "API password" and "API password confirmation" fields. These values are required to communicate with our gateway and it has to be kept confidential. Alt text
      4. Please fill in 'back request url' field: (more about back request: #266)

        back request url - defines the address, that waits for the asynchronous response from Espago gateway, after the gateway get the state of payment
      5. To provide a high level of security please fill in these fields:

        Basic login (for Back request URL) - this username will be included in authorization header

        Basic password (for Back request URL) - this password will be included in authorization header

        Merchant's website should accept only back requests with filled values of authorization header.

      6. Choose Alt text button.
      7. Remember your AppID from menu "Service". Alt text
      8. Get the public key, which is needed to create card tokens. To see it (public key), click on the "Show" next to name of service. Alt text
    • Migration from API v. 2.0

      Differences between API v.2.0 and v.3.0:

      • Every request to Espago gateway need to have a header with invormation about used API (more). If service has already APIv2.0 and API v3.0 enabled, when no header is defined default API version is 2.0.
      • The Back requests are also sent for ordinary charges (in APIv2.0 back request are sent only in subscription's payments).
      • The new format of back requests: 'Content-Type' => 'application / json; charset = utf-8 '.
        • During of migrating from version 2 to 3, you need to specify - in Merchant panel (more) - the format of "back request" for cyclic payment:
        • Back request format for ordinary charges is dependent on the version of the API which transactions are created. Accordingly application/x-www-form-urlencoded and application/json for  API v. 2.0 and API v. 3.0.
      • Enabled the Merchant 3D Secure option requires client redirection to the url address, which is sent in the response for the request. (more)
      • New version 1.2 Espago JS script used in form to create tokens (more) and possibility to use Espago iFrame.
    • Minimizing the amount of rejected payments

      Please see docs in PL
  • Card Payments

    The card payments in Espago system are authorized by Elavon. This is the default payment channel in Espago system. If you would like to integrate the card payments, you have to implement all functions from this chapter.

    • Testing

      At the test gateway you have to use the test card numbers shown below. It is not allowed to use real, working card numbers.

      Card number Description
      4242424242424242 For normal transaction, without 3D Secure and without DCC
      4012001037141112 Visa Credit with 3D Secure (Verified by Visa)
      375987000000005 American Express 3D Secure (SafeKey)
      5432670000041258 MasterCard with 3D Secure (MasterCard SecureCode)
      4012888888881881 Visa with 3D Secure (Verified by Visa) and DCC. Card currency: USD
      5555555555554444 MasterCard with 3D Secure (MasterCard SecureCode) and DCC. Card currency: HKD
      4242421111112239 Visa with DCC, without 3D-Secure. Card currency: HKD
      4917484589897107 Visa for normal (non recurring) transaction, without 3D Secure and without DCC. The card requires the use of CVV code in every transaction. Transaction made without CVV will be declined.

      Card expiration date should be any date from the future. Transaction result depends on the choice of the month. This allows you to test both scenarios: negative and positive.

      Month of expiration date Result
      01-05 transaction accepted
      06 transaction randomly accepted or rejected, useful if you test subscriptions.
      07-12 transaction declined, for each month returns other reasons:
      07 transaction declined. Issuer response codes: 04, 07, 41, 43.
      08 transaction declined. Issuer response code: 51.
      09 transaction declined. Issuer response code: 13.
      10 transaction declined. Issuer response code: 00.
      11 transaction declined. Issuer response code: 54.
      12 transaction declined. Issuer response codes: 05, 57, 61.

      CVV/CVC code in test gateway is processed according to the following rules:

      CVV Description of effect in test gateway
      683 Incorrect CVV. Transaction will be declined due to incorrect CVV.
      All other CVV Correct CVV.
    • Possible payment states

      Only state "executed" means that payment is done and money was taken from the customer's account.

      State Description
      new New payment, client's account has not been charged
      executed Payment executed, client's account was successfuly charged.
      Notice: It's possible to return the whole amount or part of the transaction amount for all executed transactions.
      rejected Payment was rejected.
      Notice: In response of the rejected transaction, you receive reject_reason parameter.
      failed Payment ended by failure
      preauthorized [Status available only when using the parameter complete=false] Money are reserved (holded) on the customer's account but not yet charged. Read more
      tds_redirected [State available only if 3D-Secure is enabled]. Customer is redirected to 3D-Secure page (bank/issuer site), Espago gateway is waiting for returning customer.
      dcc_decision [State available only if DCC is enabled]. Waiting for sending by Merchant the decision, about the payment currency chosen by customer.
      resigned Customer resigned from the autorization of payment or left payment [state available if enabled is 3D-Secure, DCC and/or MasterPass]. In case of leaving transaction with state "new", "tds_redirected" or "dcc_decision" (no customer action during 1,5 hour) transactions will change state to "resigned".
      reversed Payment was reversed before settlement.
      refunded Payment is refunded fully or partially.
    • Possible reasons of payment rejection

      • Information from "reject_reason" parameter

        Parameter "reject_reason" can be used as additional information (parameter "issuer_response_code" is more usefull and complete).

         

        Message Reason Comments
        declined Unactivated type of service (MOTO, ecommerce), also lack of funds  
        card expired Card expiration date was exceeded  
        invalid amount It refers to the transactions amount limit or number of transactions limit.  
        invalid card invalid card number, card doesn't exist  
        invalid profile invalid MID account Rejected by Elavon due to inactive MID Occurs with issuer_response_code=00
        referral A / pick up card Card marked as stolen/lost/blocked. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this reason. It may be recogenized as fraud attempt!  
        referral B Transaction needs confirmation It requires contact with issuing bank to confirm transaction
        serv not allowed Merchant does not support this particular type of a card For instance: American Express, Diners Club, in the case of no BRAM registration - also MasterCard
        3ds_not_authorized rejected during 3D-Secure Rejection due to wrong client authentication in 3D-Secure or another error during 3D-Secure check.
      • Details from "issuer_response_code" parameter

        The current table (MySQL dump) with the issuer_response_code and descriptions can be found in the "Download" section.

        Error code Meaning Proposed message
        00 Successful approval/completion Transaction approved, thank You!
        Rejected transaction on acquier/Elavon level REJECTED - An error occured. Transaction rejected by Elavon due to no response from issuer/bank, inactive Merchant account, used not supported card or incorrect card data. Please try again later or contact with Espago Support Team.
        01,02 Refer to card issuer REJECTED - Authorization's Error. Please contact your card issuer.
        03 Invalid merchant or service provider REJECTED - Authorization's Error. Please contact your card issuer and try again later.
        04,07 Pickup card (special condition, other than lost/stolen card) REJECTED - Pickup card. Please contact your card issuer and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recogenized as fraud attempt!
        05 MOTO/eCommerce/recurring inactive or not honoured REJECTED – The bank has declined the transaction due to security check (used card doesn't support payment without CVV code / recurring payment), or the funds have been frozen, or card doesn't support MOTO/internet transactions. Please check your card settings or use another card.
        13,61 MOTO/eCommerce inactive or amount limit exceed REJECTED – Please check settings of your account and configurations of limits. Please contact your card issuer and try again later.
        12 Invalid transaction REJECTED - no privileges to execute this transaction for your card. Please contact your card issuer to get more details and try again later.
        14 Invalid card number REJECTED – Invalid card number. Check entered data, if card is still active and try again.
        30 Invalid data format REJECTED – Please contact your card issuer to get more details and try again later.
        41 Pickup card (lost) REJECTED – Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recogenized as fraud attempt!
        43 Pickup card (stolen) REJECTED – Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recogenized as fraud attempt!
        51 Insufficient funds REJECTED - Insufficient funds. Please check funds on your account and try again later.
        54 Expired card REJECTED - Expired card. Please check your card or try another.
        57 Function not permitted to cardholder REJECTED – Bank/Issuer has declined the transaction as this credit card cannot be used for this type of transaction (eccommerce, MOTO or recurring). Please check your card settings or use another card.
        59 Suspected fraud REJECTED – Please contact your card issuer to get more details and try again later.
        62 Restricted card, country exclusion. REJECTED – Your card can be not supported, e.g. due to country issuer exclusion or imposition an embargo. Please contact your card issuer.
        65 Activity count limit exceeded REJECTED – Activity count limit exceeded. Change your limits settings or try again later.
        75 Allowable number of PIN-entry tries exceeded. REJECTED – Invalid activity count limit exceeded. Please check your CVV/CVC/PIN code on your card.
        78 Transaction from a new cardholder, card not been unblocked. REJECTED – Inactive card. Please activate your card and try again later.
        82, N7 Negative CVV results REJECTED - Negative CVV results. Check entered data and try again. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be fraud attempt!
        91,92,94,98 Please retry REJECTED - Refused by Issuer because Issuer is temporarily inoperative. Try again later.
        E3 Negative 3D-Secure results REJECTED - Transaction not executed due to negative 3D-Secure confirmation by client or due to 3D-Secure error.
    • Charge methods

      You can deliver the card data to our gatway in three different ways. It depends on how you would like to manage card data storage in your application. These three ways are listed below:

       

      Method Parameters Parameters description Notice
      client object client The charge request, you send to Espago gateway has to contain client parameter. This parameter has to contain the client id, which is an attribute of client object. This client object with client_id parameter has to have all the card data filled in. To get the details, please see the Clients chapter.
      token card The card parameter, you send in the request, must be equal to previously created token id. Token id is a atrribute of token object, while token object contains all card data. Token object can be created by form with included Espago JS library. To read the details of Tokens usage, please go to Tokens chapter Token with card data in it can be used only once.
      card data** card[first_name] Card owner first name All particular card data are sent to Espago gateway in the request. In this solution all the card data have to be included in the request.
      card[last_name] Card owner last name
      card[number] Card number
      card[year] Year of card expiration
      card[month] Month of card expiration
      card[verification_value] Card verification value code

       

      ** The correct solution is to transfer token ID or a customer ID (which has card data previously given by the token). For Merchant's safety reasons, the transmission of data set of cards in a query to /api/charges is not allowed, except for the test environment and a individually examined cases in a production environment. 

    • New Charge

      To create new charge please send POST request to the following address https://sandbox.espago.com/api/charges

      HTTP Parameters

       

      Parameters Description Comments
      description Description of Transaction It should contain 5-99 characters.
      amount Transaction Amount Decimal number such as 123.45
      currency Currency Three-character currency symbol in accordance with established service/MID
      client Customer ID For additional payment's channels not required. For traditional Elavon channel you should send value for one of this parameters (client or card).
      card Token ID
      recurring [optional] Adding parameter "recurring=true" enforces classification of transaction in bank as recurring transaction. This results in not checking the 3D-Secure. This parameter is needed in recurring payment (when CVV code is not used), because it significantly increase chances to accept transaction by bank (normal internet payments requier CVV code).
      complete [optional] Adding parameter "complete=false" enforces making only reservation of payment. See details in separate chapter.
      moto [optional] Adding parameter "moto=true" enforces classification of transaction as MOTO (Mail Order/Telephone Order). This results in not checking the 3D-Secure. Before use please contact Espago Tech Team.
      cvv [optional] Sending CVV token "cvv=cv_xxxxxxxxx" allow adding CVV to transaction made using client profile (when oryginal CVV was already "used"). Details in section "CVV tokens".
      positive_url [optional] URL to which the client will be forwarded after the correct transaction processing.   
      negative_url [optional] URL to which the client will be forwarded in case transaction error occurs.  
      skip_3ds [optional] Adding parameter "skip_3ds=true"results in not checking the 3D-Secure. Before use please contact Espago Tech Team.  
      reference_number [optional] Trans ref text - visible in Elavon reports. Length up to 20 characters, only alphanumeric and -_ (minus and bottom bar).  
      locale [optional] Language code in ISO 639-1 standard. Two-letter string value. Language used in web page and/or in email notification. If language is not supported, english is used.
      email [optional] E-mail address which the notification about this charge's result should be sent to. If the parameter is used with a customer profile with an e-mail address, the address sent in this parameter has a priority and is used for sending notification. String variable.
      skip_email [optional] Disables email notification - even if you send request charge with a customer profile with an email address was used. Boolean (false/true, default: false).

       

      Example of CURL

      Code using client object

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "client=client_id" -d "description=Description"

      Code using Card Token

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "card=token_id" -d "description=Description"
      • Example of Response

        3D Secure requires client redirection to the url address, which is sent in the response for the request. The redirect url address is in the "redirect_url" parameters.

        { "id":"pay_q8v53GIhU4SsaI", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"new", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":null, "created_at":1380540122 }, "issuer_response_code":"", "transaction_id":"tn_Wz8iuo426", "redirect_url":"https://sandbox.espago.com/3d-secure/tn_Wz8iuo426" }

         

        Without 3D Secure:

        { "id":"pay_q8v53GIhU4SsaI", "description":"description", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"executed", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1380540122 }, "issuer_response_code":"00", "reversable":true, "transaction_id":"tn_Wz8iuo426" }

         

        The information about changing transaction's state is sent to back request url address defined in the back request url field in the Merchant Panel

        { "id": "pay_q8v53GIhU4SsaI", "description": "Description", "channel": "elavon", "amount": 49.99, "currency": "pln", "state": "executed", "client": "cli_UrxPVeAjYh3l3C", "created_at": 1381821183, "issuer_response_code": "00", "reversable": "true" }

         
        Parameters in response from Espago may be in different order than it is showed in examples. Some parameters (eg. redirect_url) may exist or not, according to enabling 3D-Secure in merchant account or in customer's card settings, enabling DCC, etc.

         

      • Example of response after incorrect request

        When parameters in request are incorrect (ie. cc token already was used before) Espago gateway may reject a response with an HTTP code 422 or others. Such a situation should occur only in a test environment. Rejection of HTTP code 422 is a rejection of the incorrect request on API level, there is no payment attempt.

        Response to incorrect description of payment (header: HTTP/1.1 422 Unprocessable Entity)

        {"errors":[{"code":null,"message":"Description is too short (minimum is 5 characters)","param":"description","type":"invalid_request_error"}]}

        Response to second attempt to use card token (header: HTTP/1.1 422 Unprocessable Entity)

        {"errors":[{"code":null,"message":"Card token not found","param":"card","type":"card_error"}]}

        Response to attempt to use not existed (deleted) client profile (header: HTTP/1.1 422 Unprocessable Entity)

        {"errors":[{"code":null,"message":"Card can't be blank","param":"card","type":"card_error"}]}

      • Meaning of transaction_id parameter

        Transaction_id parameter (value tn_xxxxxxxxx or tr_xxxxxxxxx) is transmitted at each payment next to normal payment ID. From a technical point of view:

        • Payment ID occurs in the communications seller - Espago. Defines payment / payment order.
        • Transaction ID is present in the communication Espago - Elavon. Defines the "operation" of payment in Elavon.

        Transaction ID is available for the Merchant in the panel provided by Elavon https://www.imerchantconnect.com, so that the Merchant can check which transactions/payments are included in individual transfers made by Elavon to the bank account of the seller. Transaction ID is not necessary, but for this purpose should be read and stored.

        In most situations payment (pay_xxxxxxxxx) has assigned one transaction ID. Transaction ID is changed (updated) when:

        • first there was performed pre-authorization (the first transaction ID), and then request confirmation/charging payment (the second transaction ID)
        • payment has been refunded (payment has assigned a new transaction ID, which is ID of returning transaction).
      • Attributes of payment

        Payment has a set of parameters. All parameters are returned after creation of payment, and are later available during request about this payment or about list of payments.
        Parameter Notices Description
        id   ID of payment. Most important, it allows later checking payment status, refund, etc. It looks like pay_xxxxxxxxxxxxxxxx and has 18 or 20 characters.
        description   Your description added as parameter during request to /api/charges.
        channel   Payment channel. Currently for all payment this is "elavon", so parametr can be ignored.
        amount   Amount of payment.
        currency   Currency of payment.
        state   State of transakcji, described more detailed in "Possible payment states" chapter.
        client   ID of client used for charge. If this is single payment (just using card token) this is "temporary" client id, and should be ignored.
        created_at   Date of creation of payment, time in unix format.
        card array Parameters about used card.
        issuer_response_code   Response from bank about payment. If client is redirected to 3D-Securem this parameter have value of 00 or NULL until payment will be executed or resigned.
        transaction_id   ID of transaction. Useful for search payments in panel/reports released by Elavon, since only this ID is available in reports Elavon (there is no client ID or payment ID). The transaction is the "operation". By default one payment contains one transaction (it is execution of payment), after returning full or part of the payment is assigned here ID of transaction refunding payment.
        redirect_url optional Addres URL to redirect customar when 3D-Secure is enabled and when customer card support 3D-Secure.
        reversable optional Parameter "reversable=true" means, that transaction can be reversed. After settlement (made in night) this parameter became "false" and is not shown in payment attributes.
        tds_redirect_form optional/ array Parameter which allow to redirect client directly to bank (instead of redirecting to Espago using redirect_url). In this case, you need to redirect customer with form to this adres defined as "action" of form, method POST, with parameters PaReq, MD and TermUrl. In most situation this option is not recommended, before use please contact Espago Support Team.
    • Charge preauthorization

      This is the function that allows you to hold certain amount of money on customer's card and charge it later. To preauthorize a charge please send POST request to the following address: https://sandbox.espago.com/api/charges

      Parameters, you have to send inside this request are almost the same as they are in a single charge. You can check them above (in the new charge section). The additional parameter you have to include is complete. The default value of this parameter is true - in this case the request is interpreted as the request of a normal charge. If the value is changed to false, then the request is interpreted as preauthorization and the set funds on customer's card are blocked, but without further completion they will be released after few days.

      Preauthorized transaction can be finished by completing payment (request "complete") or by canceling (request "reverse") during few days.

      Notice:
      The maximum time of blocking funds is defined by institusion which issued the card. Usually, it is no longer than a week.

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges -u app_id:password -d "client=client_id" -d "amount=amount" -d "currency=currency" -d "description=description" -d "complete=false"

      Example of Response

      { "id":"pay_A3snPPD7YI9Bb1", "description":"description", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"preauthorized", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381821534, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "completed":false, "reversable":true, "transaction_id":"tn_prd4lSJss" }

    • Preauthorized charge capture

      To capture preauthorized charge please send POST request to the following address: https://sandbox.espago.com/api/charges/(:id)/complete

      (:id) - id of the preauthorized charge, which has to be capture

      Notice:
      The request you send could contain an amount of the capture. If you do not set the amount of capture, it will capture the amount you set on preauthorization. You could capture the customer's card on amount that is from 1% to 115% of amount you set on preauthorization.

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/(:id)/complete -u app_id:password -d "amount=35" -X POST

      Example of Response

      { "id":"pay_JETtzgkvPtHmos", "description":"description", "channel":"elavon", "amount":"35.00", "currency":"pln", "state":"executed", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381822240, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "reversable":true }

    • Getting Data of selected Charge

      To get data of existing charge please send GET request to the following address https://sandbox.espago.com/api/charges/(:id)

      (:id) - ID of selected Charge

      Example for CURL

      curl ​-H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/charge_id -u app_id:password

      Example of Response

      { "id":"pay_q8v53GIhU4SsaI", "description":"description", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"executed", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1380540122 }, "issuer_response_code":"00", "reversable":true, "transaction_id":"tn_Wz8iuo426" }

    • Displaying Group of Charges

      You could display group of charges with specified number of charges and/or on the particular page. To display specified group of charges on a particular page please send GET request to the following address: https://sandbox.espago.com/api/charges?page=1&per=10&client=client_id

      HTTP Parameters

       

      Parametrs Description Required? Default settings
      page Page number No 1 (first page)
      per List of charges No 25 (25 charges)
      client Selected Client ID No all clients

       

      Example for CURL (without HTTP Parameters)

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges -u app_id:password

      Example for CURL (with HTTP Parameters)

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges -u app_id:password -d "page=1" -d "per=5" -d "client=client_id" -X GET

      Example of Response

      { "count":5, "charges":[ { "id":"pay_O_hgcNdZn16OO3", "description":"Description of new simple charges", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"preauthorized", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821339, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "issuer_response_code":"00", "created_at":1380540122 }, "issuer_response_code":"00", "completed":false, "reversable":true, "transaction_id":"tn_b8pIy3S1T" },{ "id":"pay_q8v53GIhU4SsaI", "description":"description of recurring payment", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"executed", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "issuer_response_code":"00", "created_at":1380540122 }, "issuer_response_code":"00", "invoice":"in_xj8Hfr2-jHdf83HHa", "subscription":"sub_aaNbjskjhakJj", "transaction_id":"tn_Wz8iuo426" } ] }

      Notice:
      Parameter count in response shows number of obtained results. Lists of parameters may vary in different payments (payment before settlement has parameter "reversable", payment done during subscription has parameters "invoice" and "subscription").
    • Reversal existing Charge

      To reversal existing charge please send DELETE request to the following address https://sandbox.espago.com/api/charges/(:id)

      (:id) - ID of selected Charge

      Notice:
      Payment could be reversed only if it has not been settled yet and it's possible only for full amount of transaction. In sandbox environment settling is executed once per hour. In production environment payment becomes executed at every 24 hours (between hours 23:00 and 00:00), so only until this time they could be reversed.
      Notice:
      Payment reversing is also way to cancel preauthorization. Preauthorizations could be reversed during 1-2 weeks, according to Bank (card's issuer) politics.

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/charge_id -u app_id:password -X DELETE

      Example of Response

      { "id":"pay_ydJqgP2w7KZMvM", "description":"description", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"reversed", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381823580, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "transaction_id":"tn_AKZ71ysMF" }

    • Refund settled Charge

      To refund settled charge please send POST request to the following address https://sandbox.espago.com/api/charges/(:id)/refund where the (:id) is ID of selected Charge ("pay_xxxxxxxxxxxx").

      You can return the entire amount of the transaction or part of it. There is no possibility to undo/stop return.

      Payment can be refunded in 12 months after it's creation.

      In the case of partial refund, payment can be repeatedly refunded payment until you pay the entire amount of the original payment. Parameter refunded_amount has value already refunded amount. If you need to return full amount of payment which is partial refunded you can calculate the rest of amount (rest of money = amount - refunded_amount) or make refund request without amount.

      HTTP Parameters

       

      Parameters Description Required? Comments
      amount amount, that will be refunded No This parameter has to be less than or equal the amount of transaction. If you do not set this value, the entire transaction amount will be refunded.

      Important parameters from response

       

      Parameter Descriptions Comments
      id id of payment Value unchanged
      state status of payment After correct refund (partial or full) became "refunded"
      refunded_amount amount already refunded After full refund, refunded_amount=amount. After partial refund, refunded_amount is sum of all returns already done on this payment.
      transaction_id ID of refund transaction ID of transaction (operation) which is refunding payment. This ID is different than ID transaction made payment.

       

      Example for CURL (without HTTP parameters)

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -X POST

      Example for CURL (with HTTP parameters)

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -d "amount=n" -X POST

      Example of Response

      { "id":"pay_COy6zH9fLj1d7K", "description":"description", "channel":"elavon", "amount":"49.99", "refunded_amount":"20.00", "currency":"pln", "state":"refunded", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381823580, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "refunded_amount":"15.00", "transaction_id":"tn_AKZ71ysMF" }

  • Recurring Payments

    Recurring payments are a way of charging the client automatically loads the specified frequency. In the Espago system recurring payments consist of two main components, these are: plans and subscriptions. To use recurring payments must also create a system Espago client object assigned credit card data - based on the customer ID he is assigned to a specific subscription.

    Schematic of cyclical payments Espago system is very simple. Initially, you must define a plan which specifies the frequency with which the client will be charged and the amount of load. To start cyclic payment create a new subscription, relying on the customer ID and the ID of the plan.

    • Possible scenarios

      Regular customer charges (recurring) is possible in several ways, among which is worth to distinguish two basic scenarios:

      Scenario Application Description

      Recurring managed by Merchant

      (charges on Merchant's demand)

      If amount or period are variable.

      If next to recurring there is need for one-time payments (eg. sales).

      If Merchant's service has mechanisms for managing customers and their payments.

      For fast, one-click payment for regular customers.

      Merchant creates in Espago gateway client's profile (with card data). Next, Merchant in time chosen by him, requests payment (request to /api/charges with client ID).

      In payment request, merchant should use additional parameter "recurring=true". This parameter is needed in recurring payment (when CVV code is not used), because it significantly increase chances to accept transaction by bank (normal Internet payments requier CVV code). Also, in recurring payment 3D-Secure is not used.

      When using this scenario as oneclick payments (for returning customers), an additional parameter recurring=true should not be used (to allow 3D-Secure check). Please also consider adding CVV using CVV tokens bacause it increase security and chances to successfully charge.

      When using this scenario, there is no need to read following part about recurring (Configuration, Plans, Subscriptions, Invoices, Invoice items) because the are about second scentario, when Espago manages recurring.

       

      Recurring managed by Espago If amount and period are constant.

      Merchant defines Plan (or Plans), i.e. scheme indicating the amount and period. Next, for each client Merchant creates client profile (with card data) and create subscription (using client ID and plan ID). When subscription is created, first payment is started. If first payment is successful, subscription is active, and next payment will be performed in time defined in plan. Each payment's attempt generates back-request with information about payment status.

      To using this scenario please read next sections.

      • The problem of cards not suitable for recurring payments

        Most of the cards suitable for one-time Internet/e-commerce payments and recurring payments (if cardholder turn on this type of payments in his bank and will set the appropriate limits). There are, however, some card, which can make one-time payments online, but which are not suitable for recurring payments, eg. Maestro or few card types from Polish banks: Bank PEKAO and PKO S.A.

        In a normal scenario (creating a customer, create a subscription with the first payment) there could be a situation, where at the moment the order/subscription payment is succesfull, but later (during the recurring) all payments are rejected. This is inconvenient for both the merchant and the customer.

        To avoid this problem, it is worth to consider the use of scenario described below.

        It is also important to ensure that recurring/cyclic transactions (where is no longer used CVV/CVC code) were marked with the parameter "recurring=true". Many banks/issuers will reject normal internet payment if there is no CVV/CVC, but will accept recurring/cyclic payment without this code. Support Espago can also set option, to all payments were seen by the bank as recurring, then there is no need to add this parameter every time.

        Step Action Description

        1

        Creating client profile

        Merchant creates customer profile (with card data) in Espago gateway.

        2 Authorization of client

        Authorization on demand or automatic authorization during customer creation (you can enable it in web panel).

        SUCCESS: customer's card supports internet payment, you can go to step 3.

        FAIL: customers's card doesn't support internet payment. It means that next (recurring) payments will also fail. See: [1]* [3]*.

        3

        Creation of subscription /

        First charge /

        Second authorization

        Create a subscription (with automatical charge) or making first payment (if recurring is realised on Merchant side) or requesting again authorization on demand (if Merchant wants only chcec if card support recurring transaction.

        SUCCESS: customer's card supports internet and recurring payments. Subsequent payments will most likely also be successful. See: [2]*.

        FAIL: customer's card doesn't support recurring payments, so certainly next payment's attempts also will fail. See: [1]*.

        [1]* If the reason for the rejection is "card does not supported online/MOTO payment" or too low limits for this types of transactions, then after turning on these options/setting up this limits in the credit card options, next payments may be made successfully.

        [2]* In the case that the customer will not have sufficient money on account or card validity will expire, execution of payments will be no longer possible.

        [3]* If authorization (first transaction) was rejected due to invalid CVV/CVC (error codes 75, 82, N7) you shold not try more payments using this card! This situation could be fraud/using stolen card. Next payment may be accepted by bank because (invalid) CVV code is no more used, but it will be on Merchant responsibility.

         

      • Requirements and best practises for recurring payments

         

        Action Description
        Before subscription customer should have at least one payment with 3D-Secure.

        3D-Secure significantly increases the certainty that the client is the owner of the card.

        From september 2019 some banks may reject recurring payments if there were no 3D-Secure payments before them.

        You should minimize the repetition of failed payments, especially if the customer has several outstanding payments.

        Visa recommends (in the future this may be a requirement) to avoid a situation where several outstanding payments result in multiple repetitions of multiple payments.

        There should not be more than 1 attempt to charge the outstanding payment for the day. In practice, if the customer has several outstanding payments, then if the attempt of one (eg with the lowest amount) is rejected, then usually others are also rejected.

         

         

    • Configuration

      Please do these steps before sending first requests:

      1. Choose Alt text option.
      2. Edit Service using Alt text button.
      3. For systems which are using back request to update payment's state (almost all recurring apliances) please fill in 'back request url' field:

        back request url - defines the address, that waits for the asynchronous response from Espago gateway, after the gateway get the state of payment
         
      4. To provide a high level of security please fill in these fields:

        Basic login (for Back request URL) - this username will be included in authorization header

        Basic password (for Back request URL) - this password will be included in authorization header

        Merchant's website should accept only back requests with filled values of authorization header.

      5. Fill in time settings and states associated with execution's tries of unsuccessful transactions. On production server possible values are: 1,2,3,4 days, on test environment time may be shorter (in minutes). Recurring settings

        Possible states of subscriptions after using all available retries:

        State Description
        stop subscription Turn off subscriptions and don't create next payments. State of subscription will be changed to "inactive".
        do nothing Next payments will be created. Subscription will continue to run even if some payments will fail.
    • Plans

      Plans define scheme of recurring payments, including information obout the amount and frequency of payment. Next, based on the defined plans, you can launch subscriptions for customers.
      • New Plan

        To create new plan send POST request to below address with special parameters: https://sandbox.espago.com/api/plans

        HTTP Parameters
        Parameter Description Notices
        period_unit period unit It defines period unit, for example: day or month.
        period amount of periods Integer number. It decides about amount of periods beetwen charges i.e. if period_unit=month, period=2 will create charge every 2 months
        amount Transaction amount Decimal number, i.e. 123.45
        currency currency Currency symbol
        description plan description It should contain at least 5 characters.

        It is important to set the parameters "period" and "period_unit" in the right way. Their summary values are responsible for thes frequency of charges.

        Examples of plans:
        Value of "period_unit" Acceptable values of "period" Result
        day 1-366 Plan, that charges client's card every specified number of days
        month 1-12 Plan that charges client's card every specified number of months
        Example for CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/plans -u app_id:password -d "description=opis planu" -d "period_unit=month" -d "period=1" -d "amount=55" -d "currency=pln"

        Example response

        { "id":"pl_qtIxVOMg6m076CM", "description":"abonament", "period_unit":"month", "period":1, "amount":"55.0", "currency":"pln", "created_at":1550871586 }

      • Getting plan's data

        to get the data of existing plan send GET request to url address https://sandbox.espago.com/api/plans/(:id)

        (:id) - id of plan, which data you want to get

        Example for CURL

        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/plans/(:id) -u app_id:password

        Example response

        { "id":"pl_qtIxVOMg6m076CM", "description":"abonament", "period_unit":"month", "period":1, "amount":"55.0", "currency":"pln", "created_at":1366969540 }

      • Deleting existing plan

        To delete existing plan send DELETE request to the url address https://sandbox.espago.com/api/plans/(:id)

        (:id) - id of plan, which data you want to delete

        Example for CURL
        curl -i https://sandbox.espago.com/api/plans/(:id) -H 'Accept: application/vnd.espago.v3+json' -u app_id:password -X DELETE
        Response

        In the response you get 204 status "No content".

      • Updating data of selected Plan

        To update plan send PUT request to below address with special parameters: https://sandbox.espago.com/api/plans/(:id)

        (:id) - id of plan, which data you want to update

        Notice!
        Changing plans does not affect existing subscriptions! Only new subscriptions, which were made after updating plan data, will be charged with changed parameters. Therefore, we suggest not to update plans, better way is to create new plan.
        HTTP Parameters
        Parameter Description Notices
        period_unit period unit It defines period of time between charges, for example: day or month.
        period amount of periods Integer number. It decides about number of periods between charges.
        amount Transaction amount Decimal number, i.e. 123.45
        currency currency currency symbol
        description plan description It should contain at least 5 characters.
        Examples of plans:
        Value of "period_unit" Acceptable values of "period" Result
        day 1-366 Plan, that charges client's card every specified number of days
        month 1-12 Plan that charges client's card every specified number of months
        Example for CURL
        curl -i https://sandbox.espago.com/api/plans/(:id) -u app_id:password -d "description=opis planu" -d "period_unit=month" -d "period=1" -d "amount=55" -d "currency=pln" -X PUT
        Response

        In the response you get 204 status "No content".

      • Displaying group of plans

        To display group of plans send GET request to the url address: https://sandbox.espago.com/api/plans

        Example for CURL

        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/plans -u app_id:password
        Example response
        {
          "count":2,
          "plans":[
          {
            "id":"pl_W0pMAR48jjdLzoO",
            "description":"abonament",
            "period_unit":"month",
            "period":1,
            "amount":"55.0",
            "currency":"pln",
            "created_at":1550871586
          },{
            "id":"pl_SsYnQX-42jzW2GG",
            "description":"abonament mini",
            "period_unit":"month",
            "period":1,
            "amount":"45.0",
            "currency":"pln",
            "created_at":1550871586
          }]
        }
    • Subscriptions

      Subscriptions are kind of objects which connect client to plan.

      By default, subscription is running since it is launched (it generates the first payment) and next payment are done after period defined in Pan. Time (hour) of execution of the next payment is similar to hour of creation of subscription (payment can be called max 4 hours later). Subsription is stopped when:

      • the first payment (made during creation of subscription) is rejected. In this case subscription is not activated.
      • Merchant sends request to stop subscription,
      • one of next payments are failured (repeated three times or not repeated and if the stopping subscription in such a situation has been configured in the web panel).

      There is also possibility for launching a subscription with the delayed start (ie. with a defined date of the first payment). In such a situation there is no automatic mechanism for deactivating the subscription in case of rejection of the first payment.

      • New subscription

        To create new subscription send POST request to the url address https://sandbox.espago.com/api/subscriptions with parameters determining right plan and client.

        HTTP Parameters
        Parameter Description Details
        client client ID Mandatory parameter.
        plan plan ID Mandatory parameter.
        start_time time of starting subscription Optional parameter. By default (without this parameter) subscription is started in moment of sending request. Parameter require unix time: later than 12 hour after request and earlier than time of next period defined in plan. Details about delayed start in next chapter.

        Example CURL

        curl -i https://sandbox.espago.com/api/subscriptions -u app_id:password -d "client=(:client_id)" -d "plan=(:plan_id)"

        Example response

        We send information about subscription itself and last associated invoice.

        {
          "id":"sub_i3CoQEnqX5IKve",
          "state":"active",
          "client":"cli_buoBpPrw6rU7iC",
          "plan":"pl_vGTGxa_Kf521Sdv",
          "created_at":1373461486,
          "last_invoice":
          {
            "id":"in_MVt4vwsp7VvOTqa",
            "date":1373461485,
            "client":"cli_buoBpPrw6rU7iC",
            "subscription":"sub_i3CoQEnqX5IKve",
            "amount":"7.00",
            "currency":"PLN",
            "paid":true,
            "issuer_response_code":"00",
            "attempts":1,
            "next_payment_attempt":null,
            "created_at":1373461485
          }
        }
        Notice:
        If during creation of the subscription first payment fails this subscription expires - this is security element against the creation of a subscription using the card, which for example does not support inernet transactions or MOTO transaction. In this case, in response to a request for creating a subscription (/api/subscriptions) parameter "state" will have value "inactive".

        Back Requests

        Not only subscription is created. You'll also get an asynchronous back requests with informations about invoice (recurring payment's state) on the back request URL (More: Back request). Example back request (More: Invoices):

        {
          "id":"in_hS-KiS3N6YCzOhG",
          "date":1371631155,
          "client":"cli_OU7k00vEMGi53C",
          "subscription":"sub_QyJzN4KdzNzvmZ",
          "amount":"7.00",
          "currency":"PLN",
          "paid":true,
          "attempts":1,
          "next_payment_attempt":null,
          "created_at":1371500155
        }

        The response is sent for up to 24 hours of descending interval until a response 200 'OK' from the client application.

      • Creating subscription with delayed start

        There is a possibility to create subscription, which start time (first charge) will be declared by the Seller. To start a subscription with a delayed start, you need to use "start_time" parameter of the corresponding value in the request for creating a subscription (description above).

        • This option is usefull eg. when first period should be free.
        • After starting subscription with delayed start, it work as normal subscription.
        • You can stop subscription before first charge.

        Subscription with the delayed start has some limitations:

        • During creation of subscription there is no first attempt of payment, so there is no mechanism for deactivating the subscription in case of rejection of the first payment. Thus it is possible to run a subscription for the card, which can not be charged, because, for example, it does not support online payments and/or recurring payments.
        • To avoid this problem, the Seller shall ensure that sooner or card supports recurring billing (described earlier).
        • Date and time of launch subscription defined in the parameter "start_time" must be later than 12 hours after the request, and earlier than the time period defined as a period of plan/subscription.
      • Getting existing subscription data

        To get existing subscription data send GET request to the url address: https://sandbox.espago.com/api/subscriptions/(:id)

        (:id) - id of subscription you want to get information about

        Example CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/subscriptions/(:id) -u app_id:password
        Example response

        { "id":"sub_i3CoQEnqX5IKve", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373461486, "last_invoice": { "id":"in_MVt4vwsp7VvOTqa", "date":1373461485, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_i3CoQEnqX5IKve", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373461485 } }

      • Deleting existing subscription

        To delete existing subscription send the DELETE request to the url address: https://sandbox.espago.com/api/subscriptions/(:id)

        (:id) - id of deleting subscription

        Example CURL
        curl -i https://sandbox.espago.com/api/subscriptions/(:id) -H 'Accept: application/vnd.espago.v3+json -u app_id:password -X DELETE
        Response

        In the response you will get 204 status "No content".

      • Displaying active subscriptions

        To get a group of subscriptions send GET request to the url address: https://sandbox.espago.com/api/subscriptions

        HTTP Parameters

         

        Parametrs Description Required? Default settings
        page Page number No 1 (first page)
        per List of charges No 25 (25 charges)
        client Selected Client ID No all clients

         

        Example CURL (without HTTP Parameters)
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/subscriptions -u app_id:password
        Example CURL (with HTTP Parameters)
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/subscriptions -u app_id:password -d "client=(:client_id)" -d "plan=(:plan_id)"
        Example response

        { "count":1, "subscriptions": [{ "id":"sub_i3CoQEnqX5IKve", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373461486, "last_invoice": { "id":"in_9d7xIbhzLMkxTFm", "date":1373463196, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_i3CoQEnqX5IKve", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373463196 } }] }

      • Displaying active subscriptions of client

        To display list of active subscriptions for particular client send GET request to the following address: https://sandbox.espago.com/api/clients/(:client_id)/subscriptions

        (:client_id) - id of client, that is assigned to the subscription

        HTTP Parameters

         

        Parametrs Description Required? Default settings
        page Page number No 1 (first page)
        per List of charges No 25 (25 charges)
        client Selected Client ID No all clients

         

        Example CURL (without HTTP Parameters)
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:password
        Example CURL (with HTTP Parameters)
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:password -d "client=(:client_id)" -d "plan=(:plan_id)"   
        Example response

        { "count":2, "subscriptions": [{ "id":"sub_WbAUbaC_7KB79V", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373463500, "last_invoice": { "id":"in_I3iEPUZFxUsLUR-", "date":1373463498, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_WbAUbaC_7KB79V", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373463498 } },{ "id":"sub_FMw5DlPzK0dW9V", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373463506, "last_invoice": { "id":"in_WtlQMDFdUDpIdSq", "date":1373463504, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_FMw5DlPzK0dW9V", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373463504 } }] }

    • Invoices

      Invoice is a kind of object which is used to store informations about recurring transaction state, number of attempts and date of next payment attempt if last was rejected/failed.

      • Displaying invoice's details

        To get informations about invoice please send GET request to the following address: https://sandbox.espago.com/api/invoices/(:id)

        (:id) - id of invoice

        Example CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/invoices/(:id) -u app_id:password
        Example response

        { "id":"in_hS-KiS3N6YCzOhG", "date":1371631155, "client":"cli_OU7k00vEMGi53C", "subscription":"sub_QyJzN4KdzNzvmZ", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":1, "next_payment_attempt":null, "created_at":1371500155 }

        Additional fields:

        Name of field Meaning Possible values
        Date Planned date of charge attempt Time in Unix Format
        Paid Was invoice paid? 'True' or 'false'
        Attempts Number of executed attempts Integer
        Next payment attempt Data of execution next payment attempt Time in Unix format or 'null'
      • Displaying group of Invoice

        To get information about group of invoices please send GET request to the following address: https://sandbox.espago.com/api/invoices/

        Example CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/invoices/ -u app_id:password
        Example response

        { "count":2, "invoices": [{ "id":"in_884v5aOAcpTafgd", "date":1371474803, "client":"cli_6kYipMfvoT22KO", "subscription":"sub_UiUoPnq8nSDBYb", "amount":"55.00", "currency":"pln", "paid":false, "attempts":1, "next_payment_attempt":null, "created_at":1371474803 },{ "id":"in_95ev7TLiy_pupjd", "date":1371474813, "client":"cli_6kYipMfvoT22KO", "subscription":"sub_3NrkDVtuz1ybui", "amount":"55.00", "currency":"pln", "paid":false, "attempts":1, "next_payment_attempt":null, "created_at":1371474813 }] }

      • Displaying all invoices of client

        To get informations about all invoices of client please send GET request to the following address: https://sandbox.espago.com/api/clients/(:client_id)/invoices

        (:client_id) - id of client

        Example CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:client_id)/invoices/ -u app_id:password
        Example response

        { "count":1, "invoices": [{ "id":"in_SFRveiSmG4aorkU", "date":1372056035, "client":"cli_cl75lXjKt2kQ6u", "subscription":"sub_wYl0egJryOS7Jg", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":1, "next_payment_attempt":null, "created_at":1372056035 }] }

      • Manual paying of invoice

        If you want to enforce more retries of invoice charge you can send special POST request to the following address: https://sandbox.espago.com/api/invoices/(:invoice_id)/pay

        (:invoice_id) - id of invoice

        Notice!
        Using this request when not all retry attempts were made will decrease number of attempts made by gateway automatically!
        Example CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/invoices/(:invoice_id)/pay -u app_id:password -X POST
        Example response

        For invoice that wasn't paid:

        { "id":"in_MUL7PeIUTDwOHx8", "date":1371805245, "client":"cli_N7hldWZqSoBLva", "subscription":"sub_occMPm6-_284b3", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":2, "next_payment_attempt":null, "created_at":1371805245 }

        For invoice with state 'paid' response will return error code 422 'Unprocessable Entity'.

    • Line items

      • Create new line items

        To create new invoice item please send POST request to the following address https://sandbox.espago.com/api/invoice_items

        HTTP Parameters
        Parameter Description Field value Required?
        amount Transaction amount Decimal number, np. 123,45 Required
        currency Currency Currency code in accordance with company MID Required
        client Client ID id that allows you assign transaction to the client Required
        date Charge date Date of charge in unix time format Required
        description Transaction description Description should contain at least 5 characters. Optional
        Example CURL
        curl-H 'Accept: application/vnd.espago.v3+json'  -i https://sandbox.espago.com/api/invoice_items -u app_id:password -d "currency=currency" -d "date=unix_time" -d "amount=100" -d "client=client_id" -d "description=description"
        Example response

        { "id":"ii_1sbC2i-UHMWJXZH", "client":"cli_xNKNXh-_kWu6Qi", "description":"Description", "amount":"100.00", "currency":"PLN", "created_at":1381755981 }

      • Getting informations about line items of invoice

        To get information about line items of invoice please send GET request to the following address: https://sandbox.espago.com/api/invoices/(:invoice_id)/line_items

        (:invoice_id) - id of invoice

        Example CURL
        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/invoices/(:invoice_id)/line_items -u app_id:password
        Example response

        { "count":1, "invoice_items": [{ "id":"ii_1KZ0VBahlukLI2X", "client":"cli_OU7k00vEMGi53C", "description":"Pozycja 1", "amount":"7.00", "currency":"PLN", "created_at":1371631057 }] }

      • Deleting existing line item from invoice

        To delete existing line item send the DELETE request to the following url address: https://sandbox.espago.com/api/invoice_items/(:id)

        (:id) - id of deleting line item

        Przykład z wykorzystaniem CURL
        curl-H 'Accept: application/vnd.espago.v3+json'  -i https://sandbox.espago.com/api/invoice_items/(:id) -u app_id:password -X DELETE
        Response

        In the response you will get 204 status "No content".

  • Card Tokens

    Card tokens enable secure transfer of card data directly from the client's device (web browser, mobile device) to the Espago gateway, bypassing the Seller's system. Tokens contain only card data, can then be used by the Seller to make a payment or create a customer profile.

    Card tokens make possible to charge customer's card without storing or forwarding any cardholder data in merchant's system.

    When integration with API is used, Tokens are created by EspagoFrame (preferred) or Espago.js library. Below you can see the token usage schema. It is also described how tokens are created.

    When the card data is to be provided from the mobile application, the suggested solution is to use WebView, but it is also possible to embed the form in the application in accordance with the following requirements. In the case of implementation in a mobile application, please contact the Espago technical support team.

    • Token usage schema

      Alt text

      1. The cardholder enters the Merchant website. The cardholder downloads Espago.js on his/her device or browser from the server pointed by Espago. Espago.js create a form which is isolated from merchant page and secured by https (TLS). Downloaded by cardholder Espago.js has a public key which identifies Merchant in Espago Gateway. Credit card details must be entered in fields with "id" parameters. The form may contain additional fields defined and used by Merchant.
        Espago.js script is designed to removing card data fro form in client browser after sending them to Espago, for preventing sending it to Merchant website.
      2. When Customer clicks "Submits", the Espago.js script sends card data to Espago Gateway as request to /api/charges. If Customer put incorrect or incomplete data, Espago.js script doesn't allow to send request and give to Customer information which data is invalid.
      3. Espago Gateway recive card data, creates Token and send back Token ID to Customer web browser.
      4. The form is sent to Merchant system according to action defined form by Merchant. The ID of card token is send as the 'card_token' parameter and has value "cc_xxxxxxxxxxx".
      5. The Merchant system sends to Espago request for creating client profile (/api/clisnts) or making payment (/api/charges), and use for it the ID of the token recieved from Customer.
      6. The Espago Gateway sends response to request, with ID and details of client profile or payment. If client profile was created, Merchant should store at leas ID of client profile. Token ID will no longer be needed.
    • EspagoFrame

      EspagoFrame script creates an iframe with modal window where customer can enter credit card data. Next, data is sent to Espago, and script return ID of token to Seller website. This token can be used for payment or creating client profile.

      How it works

      After calling the form and entering card details by the payer, the script sends data directly to the Espago server. If token has been created, the script looks for the form with the identifier "espago_form" <form id="espago_form">  on the page which was called - by default - and adds here an input type of hidden with id "card_token" and token as a value:

      <input type="hidden" id="card_token" name="card_token" value="cc_xxxxxxxxxxxxx">

      This action can be changed by indicating the data-target or data-success parameter in the iframe call, as mentioned in the table below.

      Errors handling

      If the script triggers the iframe, but there is a problem in communication with the Espago server, eg due to the lack of TLS 1.0 support by the client device, a general error message will be displayed to the client.

      For debugging purposes you should use the option for error callback using data-error (described in the table below) and providing your own function, where an error message will be given as a parameter, eg 401 authorization error - in case of entering an incorrect public key.

       

      Notice!
      If the form of payment will be embedded within your website, the use of Espago iFrame or Espago JS solution is mandatory, you shouldn't host it on your own server.
      • Demo iframe test

        Click "Add card" to get new token

        Add card

         

        Demo available also in Espago test-shop : https://warzywko.espago.com/?locale=en

      • Parameters

        Important:

        Parametrs: `async`, `data-id` and `src` must be unchanged.

         

        Parameter Required?  Default value Meaning
        data-key required   String, Merchant public key
        data-live optional true String, If 'true', then requests are sent to production environment. If set to 'false', requests are sent to test environment.
        data-lang optional pl

        String, Form language (for default labels, placeholders) in ISO 639-1 standard. Available: da, de, en, et, fr, it, lt, lv, pl, ru, sv.

        data-success optional function(data) {}

        A success callback. Action inside this function will be executed when token is received.

        Note: If given, default script action is disabled - field 'card_token' will not be added to form.

        data - string; token value.

        data-error optional function(data) {}    

        An error callback. Action inside this function will be executed when error occurred.

        data - string; error code with description.

        data-onclose optional function() {}     An "on close" callback. This function is executed when user closes modal (using "x" button or "Esc" key).
        data-target optional espago_form

        Form name, where 'card_token' hidden field will be added.

        Note - if the 'data-success' parameter is specified, above action will not perform.

        data-title optional Add your card (en)

        Form title.

        Note - The default value depends on the language value of 'data-lang'.

        data-subtitle optional   The text displayed below the form title and store name (store name is taken automatically from the API Espago).
        data-button optional Save (en) The label of the submit button.
      • iFrame code example

        Sample code (minimal)

        <script async=""
          data-id="EspagoFrameScript"
          data-key="ooaY3nNkCnf7qtSRp7wD"
          src="https://js.espago.com/iframe-1.0.js">
        </script>
         

        Sample code (full)

        <script async=""
          data-id="EspagoFrameScript"
          data-key="ooaY3nNkCnf7qtSRp7wD"
          data-live="false"
          data-lang="en"
          data-success="my_success_callback"
          data-error="my_error_callback"
          data-onclose="my_onclose_callback"
          data-target="my_form"
          data-title="Add Your Card"
          data-subtitle="It's safe!"
          data-button="Save Card"
          src="https://js.espago.com/iframe-1.0.js">
        </script>
         

        To display Espago iframe contents, call the following function.

        showEspagoFrame();

         

        Sample script calling the action for display Espago iframe content after clicking on a document element with id 'addCard' (eg. A button form).

        <script>
          document.getElementById('addCard').addEventListener('click', (function(event) {
            showEspagoFrame();
          }), true);
        </script>
         

        Examples of callback functions, which will be called with generated token (in case of a successfully generated token), with an error message (in case of any error) or directly in case when user closes modal.

        <script>
          my_success_callback = function(token) {
            return console.log('Great! My token is: ' + token);
          };
        
          my_error_callback = function(error_message) {
            return console.log('Something went wrong: ' + error_message);
          };
        
          my_onclose_callback = function() {
            return console.log('User closed modal.');
          };
        
        </script>
      • Migrate from Espago.JS to Espago iframe.JS

        To migrate from the current espago.js integration, all you need to do is:

        1. remove all form fields used to sending card data;
        2. remove the script invoking Espago constructor and using create_token(); method;
        3.  follow Espago iframe integration instructions: https://developers.espago.com/en/v3#366-iframe-code-example
    • A sample form build with Espago JS library

      On the download page  there is available the latest example of the form using JS script with library jQuery.

      The sample form uses JQuery library, which is not required for Espago.js to work correctly. It is possible to implement Espago Payment Form in pure JavaScript.

    • Usage of Espago.JS script

      Notice!
      If the form of payment will to be embedded within your site, the use a script https://js.espago.com/espago-1.2.js is mandatory.

      The script must be downloaded by the client browser directly from the server Espago. Availability of script https://js.espago.com/espago-1.2.js (SLA) is the same as the Espago gateway, so there is no need to copy and use the this JS from your server.

      When using the script https://js.espago.com/espago-1.2.js form fields with data cards (card number, expiration date, the owner) could not have the "name" parameter. The Espago script need just "id". To obtain this data, you can use request to get token information or (easiest) to read them from the response from Espago gateway during creation of customer profile (query /api/clients) or payments (query /api/charges).

      • Espago Constructor

        The form will be working correctly only if operation is executed on espago object, which was created before. All the methods responsible for communication and data validation will be called for this object. Created object has to contain a merchant public key. Below there is a sample code responsible for creating the object:

        var espago = new Espago({public_key: 'public_key:'});
        Public key:
        It's a merchant authorization tool, whereby it is possible to create tokens by Espago.js library. You can get it in the API section, in "Your Sites" section. On this location it is also possible to change the public key (reset function). This key only allows to create new card tokens.
        Constructor parameters

        ParameterRequired?Default valueMeaning
        public_keyrequiredMerchant public key
        liveoptionaltrueIf value of this parameter is true, then requests from espago.js library are sent to production environment. In the case of 'false' value of this parameter, requests are sent to test environment.
        formoptional#espago_formForm name
        card_numberoptional#espago_card_numberCustomer's card number
        first_nameoptional#espago_first_nameCard owner first name
        last_nameoptional#espago_last_nameCard owner last name
        monthoptional#espago_monthMonth of card expiration date
        yearoptional#espago_yearYear of card expiration date
        cvcoptional#espago_verification_valueCard Verifictaion number
        customoptionalfalse"true" value allows to define parameters 'success' and 'error' by merchant willing.
        successoptionalfunction(data) {}A callback. Action inside this function will be executed when positive request is received.
        erroroptionalfunction(data) {}A callback. Action inside this function will be executed when errors occurs.
        submitoptionaltrueForm confirmation and execution.
      • Required form fields


        Field IDField TypeDescription
        espago_card_numbertextCustomer's card number
        espago_first_nametextFirst name on customer's card
        espago_last_nametextLast name on customer's card
        espago_monthtextCard expiration month
        espago_yeartextCard expiration year
        espago_verification_valuetextApproval code
      • create_token()

        The main action in the script that communicates with Espago gateway. Based on predefined public key, Merchant is authorized and all the data becomes tied with card token.

        espago.create_token();
        Notice!
        espago.create_token() function executes submit action. It is possible to disable this feature through adding below script:
        espago.create_token({
          submit: false,
          success: function(data) { alert("success") },
          error: function(data) { alert("error");}
        });
      • Form fields validation on Customer side

        All available validation functions are presented below. In the sample code of every function we introduced data subjected to validation. In the case of their absence, the default value is adequate form field value.

        validate_card_number()

        This method validates card number. If card number is typed with additional non-numeric characters, these characters will be ignored.

        espago.validate_card_number('4242424242424242') //true
        espago.validate_card_number('42 42 42 42 42 42 42 42') //true
        espago.validate_card_number('42 42 42') //false
        espago.validate_card_number() //default value of this method is form field 'espago_card_number' value
        validate_first_name()

        This method validates card owner first name.

        espago.validate_first_name('John') //true
        espago.validate_first_name('') //false
        espago.validate_first_name() //default value of this method is form field 'espago_first_name' value
        validate_last_name()

        This method validates card owner last name.

        espago.validate_last_name('Kowalsky') //true
        espago.validate_last_name('') //false
        espago.validate_last_name() //default value of this method is form field 'espago_last_name' value
        validate_card_date()

        This method validates card expiration date.

        espago.validate_card_date('02', '2017') //true
        espago.validate_card_date(02, 2017) //true
        espago.validate_card_date(2, 17) //false
        espago.validate_card_date() //default values of this method are form field  'espago_month' and 'espago_year' values
        validate_card_cvc()

        This method validates card cvc code.

        espago.validate_card_cvc('123') //true
        espago.validate_card_cvc('12') //false
        espago.validate_card_cvc('xyx') //false
        espago.validate_card_cvc() //default value of this method is form field 'espago_verification_value' value
      • Live demo

        https://github.com/espago/espago-1.2.js-demo
    • Getting token's data

      [Usually this request is not needed for most integration.]

      To get card token data please send GET request to the following address https://sandbox.espago.com/api/tokens/(:id)

      (:id) - ID of selected Token

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/tokens/(:id) -u app_id:password -X GET

      Example response

      { "id":"cc_J_wDRKH6jmIEb_8", "created_at":1550871586, "used":false, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"John", "last_name":"Kowalsky", "authorized":null, "created_at":1550871586 } }

    • Create tokens

      To create card token please send POST request to the following address https://sandbox.espago.com/api/tokens

      Notice:
      To create card token you need to use a publickey authetication, instead of using AppID and Password.

       

      Public key:
      It is an Merchant authorization tool. It is usied by Espago JS library, when Merchant creates a token for a customer. You can find it in "Your sites" section within the Merchant Panel. It can be reset by Merchant.

       

      Example for CURL

      curl -i https://sandbox.espago.com/api/tokens -u publickey: -d "card[first_name]=John" -d "card[last_name]=Kowalsky" -d "card[number]=4242424242424242" -d "card[verification_value]=123" -d "card[year]=2018" -d "card[month]=02" 

      Example response

      { "id":"cc_J_wDRKH6jmIEb_8", "created_at":1550871516, "used":false, "card":{ "company":"VI", "last4":"4242", "year":2018, "month":2, "first_name":"John", "last_name":"Kowalsky", "authorized":null, "created_at":1550871586 } }

      Notice:
      The used parameter takes only 'true' or 'false' values. If used parameter is false, it means that token has not been used yet i.e. to create new client or charge.
  • Customers

    This chapter describes how to create clients in Espago system. In client object you can store his card data and other information. Client object, which contains all required card data can be used to create charge multiple times.

    It is possible to create client profile without any card data, and adding card data later using function for updating client.

    In web panel there is possibility for enable/disable automatic authorization during creation of client. If it is enabled, after request to /api/client test auhthorization is made (charge and reversal for 1 PLN to check if card support Internet transactions), and in response parameter "authorized" in client profile contain authorization status (for detail see chapter below).

    • New Customer

      To create new customer please send POST request to the following address https://sandbox.espago.com/api/clients/

      HTTP Parameters

       

      Parameters Description Comments Required?
      description Short customer description Should have at least 5 characters. Not required field
      email Customer e-mail address Not required but necessary if Espago has to inform customer about changes of payments state via email. Not required field, after filling system checks e-mail format.
      card Value with ID of card token If used, this parameter should contain ID of card token created earlier. Optional/mandatory*. In most cases this is prefered way. If client should contain credit card's information this parameter should be used.
      card[first_name] Card owner name  

      Optional/for testing. It's possible to create a new client using request with all card data, but for clients with these information you should fill in all card's params. 

      It is possible to create new client without card data, but usually there is no reason to do this.

      card[last_name] Card owner surname  
      card[number] Customer card number  
      card[verification_value] CVV code  
      card[year] Customer card expiration year Values written in format YYYY
      card[month] Customer card expiration month Values in format MM. Available values: 01-12

       

      Notice:
      For security reason sending card data using Card Token is prefered/mandatory way. Sending all credit card information in request is for testing only or to use in specific applications (please contact with Espago).

      Example for CURL

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/clients -u app_id:password -d "description=Jan Kowalsky" -d "email=jan.k@example.com" -d "card=token_id"
      
      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/clients -u app_id:password -d "description=Description" -d "email=client@example.com" -d "card[first_name]=John" -d "card[last_name]=Kowalsky" -d "card[number]=4242424242424242" -d "card[year]=2019" -d "card[month]=02" -d "card[verification_value]=123"
      

      Example of Response

      { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false }

      Notice!
      If the card is properly authenticated, in the Panel Merchant near it's number in the description of the client you will see the label "Active card". In another case, the label is displayed "Inactive card". Additional paramter "issuer_response_code" allows you to identify the cause of a possible rejection of the authorization.
    • Attributes of client profile and his card

      Client profile is an object having a set of parameters. All parameters are returned after creation of client, and are later available during request about this client or about any of his payments.

      Description and possible values of card's paremeters in client profile

      Parameter Value Description
      company VI, MC, MD Information about card company: VI - Visa, MC - MasterCard, MD - Maestro, AX - American Express, DC - Diners Club, JC - JCB, SW - Switch, SO - Solo, LA - Laser. In most cases Merchant has only Visa and MasterCard cards in agreement with Elavon, so it is enough to distinguish only: VI, MC, MD.
      authorized null, true, false Information about last authoryzation, used logical values.
      null - authentication was not performed
      true - card authorization was successful
      false - card authorization was not successful
      issuer_response_code (two char) If authorized=false, this parameter will exists and will have issuer_response_code (reject reason)
      created_at (number) Time in unix format
      authorized_cvv_cvc null, true, false Parameter available when function of double authorization was used. Information about first authorization, when CVV/CVC was used. Can have logical values, the same as "authorized" parameters.
    • Deleting existing Customer

      To delete existing customer data please send DELETE request to the following address https://sandbox.espago.com/api/clients/(:id)

      (:id) - ID of selected Customer

      Example for CURL

      curl -i https://sandbox.espago.com/api/clients/client_id -u app_id:password -X DELETE
      Response

      In response you will get 204 status "No content".

    • Getting Data of selected Customer

      To get data of existing customer please send GET request to the following address https://sandbox.espago.com/api/clients/(:id)

      (:id) - ID of selected Customer

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/client_id -u app_id:password

      Example of Response

      { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false }

    • Updating data of selected Customer

      To update data of existing customer please send PUT request to the following address https://sandbox.espago.com/api/clients/(:id)

      (:id) - ID of selected Customer.

      Request should contain parameters similar to parameters during creating customer.

      Notice:
      If you update credit card data, you have to use ID of Card Token (created before update request) or enter all the data (year, month and number of a card) even if you want to change only one of them.
      Notice:
      After updating credit card data there is no possibility to revert the old card. You need to updat
      Notice:
      If service has enabled "automatic authorization of card during the creation of client" option, during updating client profile with new card data also authorization will be performed, and it will result in an updated parameter "authorized" and "issuer_response_code" in a client profile. If the automatic authorization is not enabled, when you update a card parameter the parameter "authorized" get the value "null".

      HTTP Parameters

       

      Parameters Description Comments Required?
      description Short customer description Should have at least 5 characters. Not required field
      email Customer e-mail address Not required but necessary if Espago has to inform customer about changes of payments state via email. Not required field, after filling system checks e-mail format.
      card Value with ID of card token If used, this parameter should contain ID of card token created earlier. Optional/mandatory*. In most cases this is prefered way. If client should contain credit card's information this parameter should be used.
      card[first_name] Card owner name  

      Optional/for testing. It's possible to create a new client using request with all card data, but for clients with these information you should fill in all card's params. 

      It is possible to create new client without card data, but usually there is no reason to do this.

      card[last_name] Card owner surname  
      card[number] Customer card number  
      card[verification_value] CVV code  
      card[year] Customer card expiration year Values written in format YYYY
      card[month] Customer card expiration month Values in format MM. Available values: 01-12

       

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:id) app_id:password -X PUT -d "description=John Kowalsky" -d "email=client@example.com" -d "card[first_name]=John" -d "card[last_name]=Kowalsky" -d "card[number]=4242424242424242" -d "card[verification_value]=123" -d "card[year]=2018" -d "card[month]=02"

      Example of Response

      { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2018, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false }

    • Customer Card Authorization on Demand

      You could authorize Customer card on demand by sending POST request to the following address https://sandbox.espago.com/api/clients/(:id)/authorize

      Authorization it is reserving and returning 1 PLN (or 1 EUR, etc.) to verify that the card supports e-commerce(MOTO) payments.

      • If authentication is successful, it means that the card supports online payments, has valid expiration date and currently has funds in bank account.
      • If authentication fails, it means that it is almost certain that the next payments will also fail (exception is the rejection due to temporary lack of funds or reached transaction limit of the day, but the most common reason for the rejection is not activated Internet payment or setting it's limits to 0PLN).

      In Espago's web panel you can set automatic authorization during creation of client profile. In that case, you will get authorization information already in response to client creation (and update).

      Notice:
      If authentication is the first operation performed using the card/client,  during this authorization will be used CVV code (it can be used used once), all subsequent transactions to be made without the CVV code. Part of the cards may not support payment without the CVV code (and thus not suitable for recurring payments), which may result in a situation when the authorization was successful, and further payment attempts are rejected. To avoid this, immediately after a successful authorization you should make the second authorization or payment.

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:id)/authorize -u app_id:password -X POST

      Example of Response

      { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false }

    • Displaying Group of Customers

      You could display group of clients with specified number of clients on the particular page. To display specified group of clients on a particular page please send GET request to the following address: https://sandbox.espago.com/api/clients?page=1&per=10

       

      Parametrs Description Required? Default settings
      page Page number No 1 (first page)
      per List of clients No 25 (25 clients)

       

      Example for CURL (without HTTP Parameters)

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients -u app_id:password

      Example for CURL (with HTTP Parameters)

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients -u app_id:password -d "page=2" -d "per=15"

      Example of Response

      {
        "count":33,
        "clients":[
          {
            "email":"jan@kowalski.com",
            "id":"cli_Yzij0t46pV88oR",
            "created_at":1381825758,
            "description":"Jan Kowalski",
            "card":{
              "company":"VI",
              "last4":"4242",
              "year":2017,
              "month":2,
              "first_name":"Jan",
              "last_name":"Kowalski",
              "authorized":true,
              "issuer_response_code":"00",
              "created_at":1381825758
            },
            "deleted":false
          },{
            "email":null,
            "id":"cli_KGe_jJ2ne0IfAP",
            "created_at":1381231843,
            "description":"Anna Nowak",
            "card":{
              "company":"VI",
              "last4":"4242",
              "year":2018,
              "month":5,
              "first_name":"Anna",
              "last_name":"Nowak",
              "authorized":true,
              "issuer_response_code":"00",
            },
            "deleted":false
          }
        ]
      }
      Notice:
      Parameter count in response shows number of obtained results
    • Check a credit card type

      The credit card information check function is part of the Espago REST API.

      URL: (POST)  https://sandbox.espago.com/api/clients/(:id)/check_type

      (:id) - client id

      If you check information about cardholder, you get this information:

      • issuer country
      • bank name (but only Polish banks)
      • card type

      This check can take few seconds, so it may result in slower API response. The same case is during creating of client profile, when automatyc check of card information is checked.

      Descritpion of parametres:

      Parameter Description Notice
      card_type credit card type C - credit card
      D - debit card
      - undefined/no information
      country issuer country 3 letters, ISO_3166-1_alfa-3
      - undefined/no information
      bank bank name Bank name banku
      - undefined/no information

       

      CURL Example

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:id)/check_type -u app_id:password -X POST

      Response:

      { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "card_type": "C", "country": "POL", "bank": "POWSZECHNA KASA OSZCZEDNOSCI BANK POLSKI S.A. (PKO BANK", "created_at":1381825758 }, "deleted":false }

    • Updating data of selected Customer with update_only_authorized parameter

      To update data of existing customer please send PUT request to the following address https://sandbox.espago.com/api/clients/(:id)/update_if_authorized

      (:id) - ID of selected Customer.

      Request should contain parameters similar to parameters during creating customer. Client will be only updated when card supports internet and recurring payments

      HTTP Parameters

      Parameters Description Comments Required?
      description Short customer description Should have at least 5 characters. Not required field
      email Customer e-mail address Not required but necessary if Espago has to inform customer about changes of payments state via email. Not required field, after filling system checks e-mail format.
      card Value with ID of card token If used, this parameter should contain ID of card token created earlier. Optional/mandatory*. In most cases this is prefered way. If client should contain credit card's information this parameter should be used.

       

      Example for CURL

      curl -i https://sandbox.espago.com/api/clients/(:ID)/update_if_authorized -X PUT -H "Accept: application/vnd.espago.v3+json" -u app_id:password -d "card=token_id"

      Example of Response when success

      {"updated":true, "client": { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Test", "card":{ "company":"VI", "last4":"4242", "year":2018, "month":2, "first_name":"Jan", "last_name":"NewCard", "authorized":true, "authorized_cvv_cvc":true, "created_at":1473846327 }, "deleted":false }}

      Example of Response when fail

      Parameter "updated=false" indicates that card in client profile wasn't updated, and "issuer_response_code" indicates about reject reason. In that case, object "client" is returned not changed.

      If you want detailed information about rejection of new card (not inserted in client profile) you should use GET request to /api/tokens.

       

      {"updated":false,"used_token":{"id":"cc_u82KaO3rToQx9hl","created_at":1476101947,"used":true,"card":{"company":"VI","last4":"4242","year":2018,"month":2,"first_name":"Jan","last_name":"NewCard","authorized":null,"authorized_cvv_cvc":false,"issuer_response_code":"13","created_at":1476101947}},"client":{"email":"","id":"cli_MNXfMFpu8_j3ax","created_at":1457384233,"description":"Description","card":{"company":"MC","last4":"1258","year":2019,"month":1,"first_name":"Jan","last_name":"OldCard","authorized":true,"authorized_cvv_cvc":true,"issuer_response_code":"00","created_at":1476099483},"deleted":false}}

    • Secure Page for Client creation and updating

      This is page where customer can be redirected for creating client profile with card data or updating card information in his profile. In this way, Customer put his credit card data on Espago Website, not on the seller's site (when using Espago JS or iFrame solution).

      To create link to "client_card_page"  - the secure web page, where clients can securely provides credit card data - please send POST request to the following address of API Espago:

       https://sandbox.espago.com/api/clients/card_page 

      and in response you will get the URL address to redirect customer.

      HTTP Parameters

      Parameters Description Comments Required?
      client Value with ID of customer If used, this parameter should contain ID of customer/client created earlier.  
      client[description] Short customer description Should have at least 5 characters.

      To create a new customer using generating client card page link.

       

      card[email] Customer e-mail address Not required but necessary if Espago has to inform customer about changes of payments state via email.
      store Information when save card data: all || ecommerce || recurring

      Possible values:
       - all - save all cards provided
       - ecommerce - only if card card supports internet payments
       - recurring - only if card is ready for recurring payments

      Not required field, default: all.
      check Information how to test client's credit card - nothing || ecommerce || recurring

      Possible values:
      - nothing - nothing
      - ecommerce - check if card card supports internet payments
      - recurring - check if card is ready for recurring payments

      Not required field. Default set to 'recurring' If service has enabled "automatic authorization of card during the creation of client" option (more info #259). This option override service option.
      positive_url The URL to which the client will be forwarded after card data provided.   Not required field
      negative_url The URL to which the client will be forwarded after resignation or in case error occurs.   Not required field
      title Short description for what this card will be used for Should have at least 5 characters. A brief description of the purpose for which this card is given. Not required field
      • Example for CURL

        Example with creating new client with credit card ready for recirring payments:

        curl -i https://sandbox.espago.com/api/clients/card_page -H 'Accept: application/vnd.espago.v3+json' -u app12345:Api12345 -d "client[description]=Jan Kowalski id:321" -d "client[email]=test@example.com" -d "check=recurring" -d "store=recurring" -d "title="Card for future subscription for the radio 'ABC'"

        Example with existing client:

        curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/card_page -u app12345:Api12345 -d "client=cli_tCwkq1uEXkEOrH"

        Example of response

        {"id":"cpl_uUoBWsrDqtQWvD","url":"https://sandbox.espago.com/client_card_page/cpl_uUoBfsrDqtQWvD","client":"cli_KjGn9-EXahOO4i","store":"recurring","check":"recurring","valid_to":1489110032,"created_at":1489023632,"used":false,"positive_url":null,"negative_url":null}

        Now you can also use client profile - cli_tCwkq1uEXkEOrH -  as normal - read more.

        The URL parameters contains addres url of client_card_page for this specific client - https://sandbox.espago.com/client_card_page/cpl_uUoBfsrDqtQWvD

        This link is valid for 1 hour and expires after saving card. After saving the customer card - the last screen contains a URL parameter finish=true - you can keep track of the URL addresses in a mobile WebView - and close activity after creating the card.

         

  • Back requests

    The information about changing transaction's state is sent to back request url address defined in the back request url (about back request url configuration: #207) field in the Merchant Panel.

    Back request can be sent to HTTPS and HTTP ports (443 and 80). In test env Sandbox, back request can be sent also to applications available on 8002 and 8003 ports.

    • Feedback in recurring payment

      Example of back request with information about successful payment (paid=true).

      { "id":"in_hS-KiS3N6YCzOhG", "date":1371631155, "client":"cli_OU7k00vEMGi53C", "subscription":"sub_QyJzN4KdzNzvmZ", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00","attempts":1, "next_payment_attempt":null, "created_at":1371500155, "last_payment":"pay_iq1yCYmgieM_ct" }

       

      When the subscription status changes - if the subscription stops after unsuccessful attempts option are enabled in the www panel - the back request looks like this:

      {"id":"sub_WQO0vEpk0-SrqM","state":"inactive","client":"cli_MNXfMFpu8_j3ax","plan":"pl_dxT6xBEo__fbb7y","created_at":1457559667,"last_invoice":{"id":"in_CjUBitNf9UpWdoQ","date":1460461811,"client":"cli_MNXfMFpu8_j3ax","subscription":"sub_WQO0vEpk0-SrqM","amount":"55.00","currency":"pln","paid":false,"issuer_response_code":"00","attempts":1,"next_payment_attempt":null,"created_at":1460461811,"last_payment":"pay_iq1yCYmgieM_ct"}}

    • Feedback in normal payment

      When APIv3.0 is used, every payment causes sending back request from Espago to Merchant server.

      If 3D-Secure is not used in Merchant account, recieving back request is not necessary, because it contain the same information as response to charge request. If 3D-Secure is used, reception of back request is a major source of information about the status of payments.

       

      Example back request:

      { "id": "pay_q8v53GIhU4SsaI", "description": "Description", "channel": "elavon", "amount": 49.99, "currency": "pln", "state": "executed", "client": "cli_UrxPVeAjYh3l3C", "created_at": 1381821183 ,"issuer_response_code": "00" ,"reversable": "true" }

    • Feedback during creation of token

      There is option for sending feedback from the gateway Espago at the moment of the token. In this way, the seller's service get token information from Espago, not from the client browser/mobile device. This option can be used, when there is no possibility to contact directly from Client device to Seller service.

      To enable this feature, you need to contact Technical Support Team (contact us using mail).

  • eDCC

    • What Is DCC?

      Dynamic Currency Conversion (DCC) is a service that enables international Visa® and MasterCard® cardholders the choice to pay the bill in their own currency rather than the local currency.

      DCC from Elavon can convert MasterCard® and Visa® credit and debit transactions in up to 46 currencies — more than any other payment processor — you have more opportunity to grow revenue with us. With each DCC transaction, you receive a rebate—which means the more international business you do, the more you can earn.

      The eDCC service will not be called for recurring payments (recurring = true). The cardholder does not take part in the recurring payment, so he can not make a DCC decision. In this case - when using card in a different currency than the currency of the service for recurring payments, currency conversion will be made by card issuer bank - and according to its rules.

      More information: https://www.elavon.co.uk/dcc

    • Explanation of the parameters of DCC

      Parameter Description Comments
      multicurrency_indicator Information about the transaction currency. Field present only if the payment currency is different from the currency of the site. N - Card not DCC eligible
      Y - DCC was refused by cardholder
      Z - DCC eligible card and DCC accepted by cardholder
      dcc_decision_information[cardholder_currency_name] Cardholder currency name ISO 4217
      dcc_decision_information[cardholder_amount] the amount of transactions in domestic currency card holder  
      dcc_decision_information[conversion_rate] conversion rate  
    • Start of DCC transaction

      The transaction begins as always - #213-new-charge. If the merchant has the eDCC service enabled and the Espago gateway automatically recognizes if the card qualifies for the currency conversion service. The code that uses the previously created token

      
      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "card=token_id" -d "description=Opis transakcji"
      
      • If the card has eDCC enabled, the gateway will send back the response and will wait for a decision whether the client wants to make a transaction in his native currency.
        The DCC transaction response will always show the transaction amount in the merchant's currency, the currency exchange rate, and the transaction amount in the card holder's home currency. The payment awaiting the decision takes the status = =dcc_decision

        {"id":"pay_A3HYfiWQT_ZoHO","description":"Opis transakcji","channel":"elavon","amount":"49.99","currency":"pln","state":"dcc_decision","client":"cli_cAJf7ZF3Fz4FLz","created_at":1431526723,"card":{"company":"MC","last4":"6666","year":2016,"month":1,"first_name":"Jan","last_name":"Kowalski","authorized":null,"created_at":1431526723},"issuer_response_code":"","transaction_id":"tn_0_cIL3NsS","dcc_decision_information":{"cardholder_currency_name":"USD","cardholder_amount":"13.670","conversion_rate":"0.2734", "redirect_url": "https://sandbox.espago.com/secure_web_page/tn_0_cIL3NsS"}}

      • If the card does not have eDCC enabled, the payment continues normally, the answer is as described in #286-example-of-response
    • Completing the transaction - sending the client's DCC decision

      To execute the previously booked funds in selected currecy on the customer card, a POST request should be sent to the address https://sandbox.espago.com/api/charges/(:id)/dcc_decision

      (:id) - ID of payment with DCC

      HTT Parameters

      Parametrs Description Comments
      decision The decision made whether the card is to be settled in the currency of the card holder Y or N

       

      Example for CURL

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges/(:id)/dcc_decision -u app_id:password -d "decision=Y"

      Example of Response

      The answers are the same as for a regular transaction without eDCC - #286-example-of-response - extended with information on the currency and the amount of the card holder.

      • Response with 3D-Secure

        {"id":"pay_rU_ZCn4Zedo7Nq","description":"Test Sale 1","channel":"elavon","amount":"123.45","currency":"PLN","state":"tds_prtcpt","client":"cli_4GRTE0F9Xi_rFf","created_at":1432125833,"issuer_response_code":"","transaction_id":"tn_DeLTsLlJB","redirect_url":"https://sandbox.espago.com/3d-secure/tn_DeLTsLlJB","tds_redirect_form":{"action":"https://3dtest.espago.com/PIT/ACS","method":"POST","PaReq":"4e68edef9aec6367b0da4ff2eccb923cdb4be8b846daa696182dd67a2ce27 f5f6f489785dab889e27ce799ae9b976ce021462fdf3654f2f5e3f38cb33f99d43d0197 f87f128847a2df330e2be14 bd9aded0b06625b02997be6ebecbdfeae6476eed1fd069e089b3663c7ae6da4bf666c9db c8acc1b87554f99c203be46 5c9b7aa456ac8d97c878a2b73bc5688afd4925de3aac8a2ae0a53c05ca26cce4cf360053 22c19cc0a8efbc99e7797c7 b4396cfc3fd4e0fb522b1c07eedb2df28496f7168fd03247b3837051ef045da7ae5aec3d 5f4671a2aca18d6990c2138 f8c0a6aea56575645e40df5c12253d77927aa89bf3c4337d93da43ff96e2c654226dd800 23cb7a8c34d96c417a9ddb8 d50632c89634b7c6ca510ea46a27c76212beff4c5d46b90ed5020d57543502013a2369f8 b5a566c7b790ec46cc89156 037f1e7835a9f2fae29e3a2dea3c22514b2f9b0dc8577c8fae5f68471e84900e7b973325 7b2fde44a1c65bf1c6c231f 5699d073096f677421d67e4a8b910c9c6027ccd60dd425a927d4687be69dd8f6a40ce201 9c3d4e7e9ad8db82e9d6729 806b07770229e8c8a6aef7026c1aaefd014f968bd0b4e788399eb9d085d2d2ad5d2a4090 3cbb3ac913e9c35919fea96 2aaa96072135d17ac48e10521d2883374e60e03cdf36b154e168e9cccf73015e1b24d137 988f4a22b5af1","MD":"854","TermUrl":"https://3dtest.espago.com/visa3dmpi/servlet/ParesListener"},"multicurrency_indicator":"Z","dcc_decision_information":{"cardholder_currency_name":"HKD","cardholder_amount":"261.55","conversion_rate":"2.1187"}}

      • Response without 3D-Secure

        { "id": "pay_FMj2Q9N7e6Yv2z", "description": "Test Sale 1", "channel": "elavon", "amount": "123.45", "currency": "PLN", "state": "executed", "client": "cli__aNPjOXggmnfSZ", "created_at": 1432124395, "issuer_response_code": "00", "reversable": true, "transaction_id": "tn_PMN_nN0Am", "multicurrency_indicator": "Z", "dcc_decision_information": { "cardholder_currency_name": "HKD", "cardholder_amount": "261.55", "conversion_rate": "2.1187" } }

    • Downloading exchange rates

       

      To get data of exchange rates please send GET request to the following address https://sandbox.espago.com/api/dcc/rates

      Example for CURL

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/dcc/rates -u app_id:password

      Example response

      {"timestamp":"2015-05-11T00:00:00+02:00","currency_name":"PLN","currency_code":"985","rates":{"AUD":"0.3531","CAD":"0.3343","CHF":"0.2618","DKK":"1.905","EUR":"0.2554","GBP":"0.1835","HKD":"2.1187","JPY":"32.6429","NOK":"2.1513","NZD":"0.3551","SEK":"2.3709","SGD":"0.3691","USD":"0.2734","ZAR":"3.3076","INR":"17.1971","KRW":"295.599","RUB":"14.6586","BMD":"0.2734","ISK":"37.3917","MYR":"0.9939","SAR":"1.025","CZK":"6.9958","QAR":"0.9951","TTD":"1.7222","AED":"1.0042","HUF":"75.8934","BHD":"0.103","KWD":"0.0826","THB":"8.8497","ILS":"1.0784","TWD":"8.5047","BBD":"0.5458","OMR":"0.1052","BSD":"0.2734","KES":"25.6168","ARS":"2.4242","CNY":"1.6952","COP":"679.651","MAD":"2.7304","MXN":"4.2133","PAB":"0.2734","RON":"1.1335","TRY":"0.7339","UAH":"6.1786","BRL":"0.8282"}}

  • CVV tokens

    CVV code can be used only once. To execute next payment using client profile with the CVV code, customer should enter CVV code (use EspagoFrame or Espago JS to create CVV token) and send it as one of parameters of the payment.

    Function of adding CVV is specially usefull as an additional authentication at multiple payments initiated by the customer (eg. shopping in a store, payment in a mobile application). Adding CVV also increases the efficacy of payments, as it allows charging of cards that do not work without the CVV code (see section: The problem of cards not suitable for recurring payments)

    CVV token can be used in 24h after creating, there is no option to store CVV for later multiple payments.

    • New CVV token

      To create CVV token please send POST request to the following address https://sandbox.espago.com/api/cvv

      Creating CVV token in direct request (not using Epsago-CVV script) is alowed only in mobile applications. In other cases please contact Espago Technical Support Team.

      Notice:
      To create CVV token you need to use a publickey authetication, instead of using AppID and Password.

       

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/cvv -u publickey: -X POST -d "verification_value=123"

      Example response

      {"id":"cv_BhJER4yDz2k3TKE","valid_to":1441792964,"created_at":1441706564,"used":false}

      Notice:
      The used parameter takes only 'true' or 'false' values. If used parameter is false, it means that token has not been used yet, and that it can still be used to charge.
      CVV token is valid only 24h.
    • Using EspagoFrame to create CVV Token

      To create CVV token you can use EspagoFrame - iframe with modal window described in EspagoFrame,, in this case - only CVV. Next, data is sent to Espago, and script returns CVV token to callback function or form. This token can be used to charge request using saved client profile.

      How it works

      After calling the form and entering CVV by the cardholder, the script sends data directly to the Espago server. If token has been created, the script looks for the form with the identifier "espago_form" <form id="espago_form">  on the page where it was called - by default - and adds an input type of hidden with id "cvv_token" and token as a value:

      <input type="hidden" id="cvv_token" name="cvv_token" value="cv_xxxxxxxxxxxxx">

      This action can be changed by indicating the data-target or data-success parameter in the iframe call, as mentioned in the table below.

      • Parameters

        Important:

        Parametrs: `async`, `data-id` and `src` must be unchanged.

         

        Parameter Required?  Default value Meaning
        data-key required   String, Merchant public key
        data-cvv-only required   String, if 'true', EspagoFrame is set in CVV mode - only CVV field will be displayed.
        data-company optional   String, indicates saved card company, this company logo will be displayed as card info next to CVV field. Available: AX, DC, DI, JC, MC, MD, UP, VI.
        data-last4 optional   String, indicates saved card number last 4 digits , will be displayed as card info next to CVV field.
        data-valid-to optional   String, format: MMYYYY, indicates saved card validation date, will be displayed as card info next to CVV field.
        data-live optional true String, If 'true', then requests are sent to production environment. If set to 'false', requests are sent to test environment.
        data-lang optional pl

        String, Form language (for default labels, placeholders) in ISO 639-1 standard. Available: da, de, en, et, fr, it, lt, lv, pl, ru, sv.

        data-success optional function(data) {}

        A success callback. Action inside this function will be executed when token is received.

        Note: If given, default script action is disabled - field 'card_token' will not be added to form.

        data - string; token value.

        data-error optional function(data) {}    

        An error callback. Action inside this function will be executed when error occurred.

        data - string; error code with description.

        data-onclose optional function() {}     An "on close" callback. This function is executed when user closes modal (using "x" button or "Esc" key).
        data-target optional espago_form

        Form name, where 'card_token' hidden field will be added.

        Note - if the 'data-success' parameter is specified, above action will not perform.

        data-title optional Add your card (en)

        Form title.

        Note - The default value depends on the language value of 'data-lang'.

        data-subtitle optional   The text displayed below the form title and store name (store name is taken automatically from the API Espago).
        data-button optional Save (en) The label of the submit button.
    • Usage of Espago.JS script to create CVV Token

      To accept the CVV code and create a token CVV, please use the form using JS script espago-1.2. This script sends the CVV code directly from the form (client browser) into the gateway Espago, next recieve CVV token and sends its ID (as parameter "cvv_token" with the value like "cv_xxxxxxxx") with the form to the merchant website.

      Address of actual version of script: https://js.espago.com/espago-1.2.js 

      Demo: https://github.com/espago/espago-1.2.js-demo

      In the script there should be used "Public Key", the same as in the Espago JS used to create normal credit card script.

    • New Charge with CVV token

      HTTP Parameters

      An additional parameter in request to /api/charges is the parameter cvv

      Parameters Description Comments
      cvv CVV token ID, optional To use a previously created CVV set the "cvv=cvv_token_id" 

       

      Example of CURL

      Code using client object

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "client=client_id" -d "description=Opis transakcji" -d "cvv=cvv_token_id"

      Code using Card Token

      curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "card=token_id" -d "description=Opis transakcji" -d "cvv=cvv_token_id" 
    • Getting CVV token's data

      To get card token data please send GET request to the following address https://sandbox.espago.com/api/cvv/(:id)

      (:id) - ID of selected CVV Token

      Example for CURL

      curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/cvv/(:id) -u app_id:password -X GET

      Example response

      {"id":"cv_BhJER4yDz2k3TKE","valid_to":1441792964,"created_at":1441706564,"used":false}

  • Masterpass

    MasterPass will be available on the Espago from March 2015

    • How MasterPass works?

    • MasterPass API

      Full documentation and description of MasterPass, is available on the Mastercard website: https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+Services+-+Documentation

      An example of integration MasterPass demo is available on the espago demo website: https://warzywko.espago.com (it is also described how to use the test wallet)

      Lightbox integration is required to launch the MasterPass user interface. To invoke the Lightbox, merchants must include the following scripts to the page on which they are adding the Buy with MasterPass button:

      1. jQuery library
      2. Espago-masterpass script - the same for sanbox and production:
        <script src="https://developers.espago.com/espago-masterpass.js" type="text/javascript"></script>
      3. MasterPass Script
        for sandbox:
        <script src="https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js" type="text/javascript"></script>
        for production:
        <script src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js" type="text/javascript"></script>
      • Normal transaction - Standard checkout

        Before starting the transaction should save your shopping data locally. Especially parameters session_id and the amount of the transaction.

        The transaction begins by calling the payment MasterPass using the script Espago-MasterPass.js, by the customer.

        • Standard Checkout User Flow

          The following steps explain the standard MasterPass checkout process flow that the merchant must use for a non-registered (guest) user on their site: 

          1. The consumer clicks the Buy with MasterPass button.
            Transaction parameters are transmitted to Espago using jQuery and the POST method, and next the Lightbox(MasterPass UI) is invoked. 

          2. The consumer logs in to their wallet. 

          3. The consumer selects their payment method and shipping address.

          4. The consumer reviews and submits the order. 

          5. After checkout is complete, MasterPass will return context to the Espago. Espago redirect the consumer to positive_url or negative_url (or earlier also redirect to bank if 3D-Secure is enabled for Merchant and customer credit card).

          6. After the payment is made, an confirmation of payment(back_request) is sent from Espago gateway to Merchant's website. 

          Full process flow is avaiable on demo site https://warzywko.espago.com, and on video below:

           

        • Examples of use espago-masterpass.js

          Example form:

          <form accept-charset="UTF-8" id="masterpass_espago_form" method="post">     <input id="masterpass_action" name="masterpass_action" type="hidden" value="checkout" />     <input id="app_id" name="app_id" type="hidden" value="app12345" />     <input id="session_id" name="session_id" type="hidden" value="NF9r5x1at8MprEvqKmPh" />     <input id="amount" name="amount" type="hidden" value="123.00" />     <input id="currency" name="currency" type="hidden" value="PLN" />     <input id="description" name="description" type="hidden" value="payment_id:1" />     <input id="api_version" name="api_version" type="hidden" value="3" />     <input id="checksum" name="checksum" type="hidden" value="9ecbd7782c6152d71cf963448a2b7daf" />     <input id="shopping_cart_items_0_description" name="shopping_cart_items[0][description]" type="hidden" value="Szkolenie 8h" />     <input id="shopping_cart_items_0_quantity" name="shopping_cart_items[0][quantity]" type="hidden" value="1" />     <input id="shopping_cart_items_0_value" name="shopping_cart_items[0][value]" type="hidden" value="123.0" />     <input id="shopping_cart_items_0_image_url" name="shopping_cart_items[0][image_url]" type="hidden" value="https://example.com/image.jpg" />     <button name="button" type="submit">Buy with MasterPass</button> </form><a href="http://www.mastercard.com/mc_us/wallet/learnmore/en" target="_blank">Learn more</a>

           

          Connecting Espago MasterPass function to the form Buy with MasterPass:

          <script> $(document).ready(function(){ var espago_masterpass = new EspagoMasterPass({public_key: 've9SCMKLFabsHzX8HhTe', custom: true, live: false}); $("#masterpass_espago_form").submit(function(event){ event.preventDefault(); espago_masterpass.create_js(); }); }); </script>

           

           

          When the consumer clicks the Buy with MasterPass button lighbox open. The consumer logs in to their wallet. The consumer selects their payment method and shipping address. The consumer reviews and submits the order. After transaction Espago redirect the consumer to positive_url or negative_url.

           

          Transaction parameters are transmitted using jQuery and the POST method to the address:

          sandbox URL: https://sandbox.espago.com/api/masterpass
          production URL: https://secure.espago.com/api/masterpass

          Transaction parameters:

           

          Parameters Description Required? Notice
          masterpass_action kind of MasterPass action Required "checkout" - form simple normal transaction
          app_id application ID Required
          session_id merchant session ID/transaction ID Required random uniq string
          amount transaction amount  Required  
          currency transaction currency Required  
          description transaction description Required  
          api_version api version Required 3
          checksum checksum Required

            Checksums (md5 sum consisting of the parameters)

          Parameters used to generate checksum: app_id +|+ session_id +|+ amount +|+ currency +|+ checksum_key. The fields’ separator: "|".

          md5 for: app123|hoQuNQAam|1.23|PLN|ac2bb
          equals: 963c1ab6d74d1340176c581867d951de

          checksum_key  - A random string, used to calculate a checksum value - you can find in Merchant Panel
          sandbox.espago.com/en/merchant/services

          Shopping cart details, where INDEX is a number 0-100 (optional)
          shopping_cart_items[INDEX][description] Item description Required  
          shopping_cart_items[INDEX][quantity] item quantity Required  
          shopping_cart_items[INDEX][value] item price  Required  
          shopping_cart_items[INDEX][image_url] item image URL No  HTTPS/SSL
        • Example of response in back_request

          After the payment is made, an confirmation of payment is sent from Espago gateway to Merchant's website (to address defined as "URL back request").

          {"id":"pay_5-gesOlp_ZIbuJ","description":"payment_id:124","channel":"masterpass","amount":"123.00","currency":"PLN","state":"executed","client":"cli_IJRMhA6p1-Tpy8","created_at":1425756633,"issuer_response_code":"00","reversable":true,"masterpass":{"brand_name":"MasterCard","billing_address":{"city":"toronto","country":"CA","countrySubdivision":"CA-ON","line1":"1212 no address","line2":"","line3":"","postalCode":"m3v2w2"},"shipping_address":{"city":"Poznań","country":"PL","countrySubdivision":"Wielkopolskie","line1":"Nowakowa 12/3","line2":"","line3":"","postalCode":"60-123","recipientName":"Jan Kowalski","recipientPhoneNumber":"PL+48-61123123123"},"contact":{"firstName":"JOE","lastName":"Test","country":"US","emailAddress":"joe.test@email.com","phoneNumber":"1-9876543210"}}}

        • Displaying “Buy with MasterPass” Button Image

          • PL https://www.mastercard.com/mc_us/wallet/img/pl/PL/mcpp_wllt_btn_chk_147x034px.png
          • EN https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png
          • another size/resulutions:
            • /mcpp_wllt_btn_chk_147x034px.png
            • /mcpp_wllt_btn_chk_160x037px.png
            • /mcpp_wllt_btn_chk_166x038px.png
            • /mcpp_wllt_btn_chk_180x042px.png
            • /mcpp_wllt_btn_chk_290x068px.png 
            • /mcpp_wllt_btn_chk_317x074px.png 
            • /mcpp_wllt_btn_chk_326x076px.png 
            • /mcpp_wllt_btn_chk_360x084px.png
        • MasterPass “Learn More” Page

          In addition to the MasterPass checkout button and acceptance mark, MasterPass also requires merchants to provide a link to Learn More page which can be used by the consumers to get additional information about MasterPass.

          It is recommended that you place the link in close proximity to the Buy with MasterPass button

          The Learn More page is available in multiple languages and can be accessed from the following link. For the list of all available languages, refer to the MasterPassDigital Assets – Buttons and Learn More Links document.

          The following URLs contain examples of the Learn More

          • English - http://www.mastercard.com/mc_us/wallet/learnmore/en
          • Polish - https://www.mastercard.com/mc_us/wallet/learnmore/pl/PL/
          • Swedish - http://www.mastercard.com/mc_us/wallet/learnmore/se
          • French - http://www.mastercard.com/mc_us/wallet/learnmore/fr
          • Italian - http://www.mastercard.com/mc_us/wallet/learnmore/it
          • Spanish -http://www.mastercard.com/mc_us/wallet/learnmore/es
        • Testing

          The following pre-set Masterpass wallet accounts, which have previously been available for sandbox testing, are no longer available:

          • joe.test@email.com
          • joe.test3@email.com
          • 3ds.masterpass+securecode@gmail.com
          • 3ds.masterpass+verifiedbyvisa@gmail.com

          To conduct testing in the sandbox environment, you must first set up your own Masterpass test wallet account.

          Click here for further details on Sandbox Testing steps. The steps are different for merchant sites in US and those globally. https://developer.mastercard.com/page/masterpass-testing

          Remember that, transaction result depends on the choice of the month. This allows you to test both scenarios: negative and positive. Month of expiration date 01- 05 transaction accepted. So You should choose verified(anyone can add wrong card number to this test masterpass account) card, that has correct "valid until" month. 

  • Payment page

    The use of the payment page Espago means redirecting the client to the gate Espago, for which the customer will give data cards to make payments. At this moment, Espago's payment page can be used only for single payments (there is no option to create client profile to use it in recurring payments).

    Payment using payment page Espago as follows:
    1. After chosing purchases and selecting Espago payment customer submits the form using the POST method to the address of the Espago gateway to path /secure_web_page
    2. Payment page is displayed to customer, pages includes Merchant's name and the amount to be paid. The customer provides the card data and clicks Pay.
    3. Depending on the included features on the Merchants's account and the type of customer card, the customer may have to choose the currency of payment (DCC) and/or may be redirected to the bank website (3D-Secure).
    4. After the payment is made, the customer is redirected to the Merchant's page positive_url or negative_url defined in form sent on beginning of payment, or if it was not defined in this form to URLs defined in the panel in gateway Espago.
    5. After the payment is made, an confirmation of payment is sent from Espago gateway to Merchant's website (to address defined as "URL back request").

    Demo avaiable: https://warzywko.espago.com/

    • Example form

      To create new charge please send POST request to the following address:

      sandbox URL: https://sandbox.espago.com/secure_web_page
      URL: https://secure.espago.com/secure_web_page

      Transaction POST parameters:

      Parametr Description Required? Notice
      api_version api version Required 3
      app_id application ID Required
      kind transaction kind Required sale or preauth(hold certain amount of money on customer's card and charge it later)
      session_id merchant session ID/transaction ID Required Random, unique character string generated by Seller
      amount transaction amount Required two decimal places, separated by a dot, eg. 10.00, 1.23, 1.20
      currency transaction currency Required  
      title transaction title Required

      Payment description - will be displayed as a payment title at the top of payment card form, e.g. "Order 123/2019".
      Should be between 5 and 100 characters.

      This parameter "title" from de form will be available as payment parameter "description".

      description client description No Description of customer, not payment.
      email client email No  
      positive_url URL to which the client will be forwarded after the correct transaction processing  No  
      negative_url URL to which the client will be forwarded in case transaction error occurs No  
      locale transaction language No pl, en, da, ru, sv
      reference_number reference number No Trans ref text - visible in Elavon reports. Length up to 20 characters, only alphanumeric and -_ (minus and bottom bar).
      ts timestamp Required  
      checksum checksum Required

        Checksums (md5 sum consisting of the parameters) Parameters used to generate checksum: app_id + | + kind + | + session_id + | + amount + | + currency + | + ts + | + checksum_key.  The fields’ separator: "|".

      md5 for: app123|sale|hoQuNQAam|1.23|PLN|1444044688|ac2bb
      equals: ec4a3d29787495ca3dc36fb548d93c91

      Shopping cart details, where INDEX is a number 0-100 (optional)
      shopping_cart_items[INDEX][description] item description Required  
      shopping_cart_items[INDEX][quantity] item quantity Required  
      shopping_cart_items[INDEX][value] item price  Required  
      shopping_cart_items[INDEX][image_url] item image URL No  HTTPS/SSL

       

      Example:

      <form accept-charset="UTF-8" action="https://sandbox.espago.com/secure_web_page" id="espago_secure_web_page" method="post">
      <input id="api_version" name="api_version" type="hidden" value="3" />
      <input id="app_id" name="app_id" type="hidden" value="app12345" />
      <input id="kind" name="kind" type="hidden" value="preauth" />
      <input id="session_id" name="session_id" type="hidden" value="hoQuNQAamMAvSKYXEKzM" />
      <input id="amount" name="amount" type="hidden" value="1.23" />
      <input id="currency" name="currency" type="hidden" value="PLN" />
      <input id="title" name="title" type="hidden" value="payment_id:294" />
      <input id="description" name="description" type="hidden" value="Jan Kowalski" />
      <input id="email" name="email" type="hidden" value="jan.kowalkis@example.com" />
      <input id="positive_url" name="positive_url" type="hidden" value="http://example.com/payments/ok" />
      <input id="negative_url" name="negative_url" type="hidden" />
      <input id="ts" name="ts" type="hidden" value="1444044688" />
      <input id="checksum" name="checksum" type="hidden" value="ac2bb1cdb8b8052895f2246e14aad7d5" />
      <input id="shopping_cart_items_0_description" name="shopping_cart_items[0][description]" type="hidden" value="Pakiet 1" />
      <input id="shopping_cart_items_0_quantity" name="shopping_cart_items[0][quantity]" type="hidden" value="1" />
      <input id="shopping_cart_items_0_value" name="shopping_cart_items[0][value]" type="hidden" value="1.23" />
      <input id="shopping_cart_items_0_image_url" name="shopping_cart_items[0][image_url]" type="hidden" value="https://example.com/products/0.png" />
      <div class='button'>
      <button name="button" style="float:left" type="submit">Buy</button>
      </div>
      </form>
    • Payment with Champion

      To register a payment with Champion please send POST request to the following address  https://sandbox.espago.com/api/secure_web_page_register

      (:service_client_id) - client ID in a Merchant system, has to be uniq, because of using in a automatic logging in

      (:redirect_url) - link, where a user should be redirected to pay

      A result is sent by Back requests.

       

      Example for CURL

       

      curl -i https://sandbox.espago.com/api/secure_web_page_register -X POST -H 'Accept: application/vnd.espago.v3+json' -u app_id:password -d 'amount=49.99' -d 'currency=PLN' -d 'description=Transaction description' -d 'kind=sale' -d 'positive_url=https://......' -d 'negative_url=https//.....' -d 'service_client_id=xxxxxx' -d 'client_description=xxxxx'

       

      Example response

       

      {"id":"pay_IZTq8l_qaHuOHH","description":"Opis transakcji","amount":"49.99","currency":"PLN","state":"new","created_at":1550224439,"transaction_id":"tn_CLN2HhetI","redirect_url":"https://sandbox.espago.com/secure_web_page/tn_CLN2HhetI"}

       

  • Integration using Przelewy24

    There is possibility to use Espago/Elavon card payments as one of payment type in module Przelewy24 (offered by Dialcom24 Sp. z o.o). In this scentario there is no need to integrate directly with Espago gateway, Merchant need to make integration only with Przelewy24 service.

    • Restrictions

      The integration of card payments Espago / Elavon through Przelewy24 is associated with the following restrictions:
      1. One account (one MID generated by Elavon) can be used only in Przelewy24 OR directly using Espago gateway.
      2. Przelewy24 can be used only for single payment, there is no recurring option.
      3. In Przelewy24 test environment there is no card payment method. This method will appear only in production environment.
    • Integration

      Integrating of card payment Espago/Elavon using Przelewy24:

      1. Create account in Przelewy24 service and make agreement (online, next steps you can do in the same time)
      2. Integrate your shop/service/website with Przelewy24 module, eg. by installing module and configure account settings
      3. Send to Espago Support information about integration through Przelewy24 and send your ID (or multiple ID's) from P24 system. Card payments will be integrated by Espago/Przelewy24 into this account.

       

      Additional information:

  • Visa Checkout [DRAFT]

    Demo działania Visa Checkout jest dostępne w testowym sklepie Espago https://warzywko.espago.com/

    Ogólny zarys integracji Visa Chcekout (VCO) u sprzedawcy w połączeniu z Espago jest przedstawiony na poniższym rysunku:

    • Sprzedawca tworzy konto swojej firmy (testowe konto można założyć tutaj: https://developer.visa.com/portal/#users/new)
    • Sprzedawca wybiera Espago z listy PSP
    • Sprzedawca podłącza skrypt VisaCheckout.JS do swojej strony (https://developer.visa.com/products/visa_checkout/guides#adding_visa_checkout)
      • (1) - po załadowaniu strony, guzik VISA checkout się aktywuje
      • (2) - po przyciśnięciu guzika VISA Checkout uruchamiany jest (na podstawie parametrów ustawionych przez sprzedawcę - m.in. klucz publiczny Espago) VCO lighbox
        •     V.init({
                apikey: "1C4SZHXUC8SHT1VDY44413BB7bDfS0maObSRu6Euq5AGAi6eo",
                paymentRequest:{
                  currencyCode: "PLN",
                  subtotal: "5.0",
                  total: "5.0",
                  customData: {
                        "nvPair": [
                             { "name": "customName1", "value": "customValue1" },
                             { "name": "customName2", "value": "customValue2" }
                  ]},
                  orderId: "order_no_123",
                  promoCode: 'Test promo'
                },

              });
      • (3) - klient podaje dane karty/wybiera dane/zakłada konto i klika Dalej
      • (4) - dane z VCO są przesyłane do sprzedawcy, może je wyświetlić i wykorzystać
      • (5) - parametr "call ID" z danych odebranych przez VCO jest przesyłany do Espago wraz z całym zapytaniem obciążającym (analogiczne do standardowego zapytania do Espago, z tym, że call ID zamiast danych karty)
    • Espago
      • (6-7-8-9-10-11-12-13-14) Espago pobiera dane klienta z VCO i tworzy płatność kartową, zwraca dane i wysyła BackRequest

     

    Szczegółowa dokumentacja techniczna VisaCheckout: https://developer.visa.com/products/visa_checkout/guides#getting_started

     

    • Request

      Utworzenie nowego obciążenia następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/visacheckout".

      HTTP Parameters

      Parametr Opis Uwagi
      call_id id zapytania VCO

      ID zapytania uzyskanego z Visa Checkout

      amount Kwota transakcji Liczba dziesiętna, np. 123.45
      currency Waluta Trzyliterowy symbol waluty zgodny z posiadanym MID
      description Opis transakcji Musi składać się z 5 do 99 znaków.

       

      Przykład z wykorzystaniem CURL

      Kod wykorzystujący funkcjonalność obiektów klienta

      curl -i https://sandbox.espago.com/api/visacheckout -u app_id:password -d "amount=49.99" -d "currency=pln" -d "call_id=3931755271838381802" -d "description=Opis transakcji"

      Przykładowa odpowiedź

      {"id":"pay_bJuV0IYLSzRFSA","description":"Opis transakcji","channel":"visacheckout","amount":"49.99","currency":"pln","state":"executed","client":"cli__lebHEMtR-HGIF","created_at":1486118378,"card":{"company":"VI","last4":"4242","year":2022,"month":4,"first_name":"Adam","last_name":"Kowalski","authorized":null,"created_at":1486118379},"issuer_response_code":"00","reversable":true,"transaction_id":"tn_RmNqMSO69","visacheckout":{"billing_address":{"personName":"Adam Kowalski","firstName":"Adam","lastName":"Kowalski","line1":"Uliczna 16/1","streetNumber":"16/1","streetName":"Uliczna","city":"Pozna\u0144","postalCode":"60-412","countryCode":"PL","phone":"123123123","default":false},"shipping_address":{"verificationStatus":"NOT_VERIFIED","personName":"Adam Kowalski","firstName":"Adam","lastName":"Kowalski","line1":"Uliczna 16/1","streetNumber":"16/1","streetName":"Uliczna","city":"Pozna\u0144","postalCode":"60-412","countryCode":"PL","phone":"123123123","default":false}}}