• Preliminary assumptions

    This documentation contains the information needed to integrate the merchant's website with the payment gateway Espago in older (but still supported) API version 2.0. This part of documentation will be not updated. For new and updated documentation please go to APIv3.0 documentation.

    • 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. Webpanel with the ability to view and set parameters and viewing the test payments, queries and responces is available at https://sandbox.espago.com
      4. Features which should be tested during the integration include:
        • the creation of tokens,
        • charging cards/maing payments,
        • obtain information about payments made,
        • Reversal ant returning of the transaction (no need to implement these features, but useful to test curl queries),
        • The creation of customer profiles and manage them (if there is business need, for example 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).
      5. After integrating to the production environment, test environment still remains available to the Merchant.
      6. 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).
        • Turn on / turn off the ability to authorize client on-demand and/or automatic (disabled by default).
        • Create a new user with access to the panel.
        • Provide answers and help solving problems associated with integration.
      7. At download there are available sample files accelerating integration.
    • General description of the gateway

      1. All operations related to payments are carried out using the query to the API (Application Programming Interface).
        • This means that there is no "payment page" to which you must redirect customers.
        • Correctly designed form of payment (using a JS script provided by Espago) is be placed in your website.
        • Ability to redirect to the "payment page Espago" reappears in the next version of the API in the first quarter of 2015.
      2. An application URL address for a test environment is https://sandbox.espago.com/api
      3. An application architecture is compatible with REST standard.
      4. Initial data to Espago gateway should be send using HTTP PARAMS and the result data is returned in JSON format.
      5. Espago provides a script in JavaScript https://js.espago.com/v1/. For most websites the use this script is mandatory. 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 (it dumps from merchant responsibility for the storage and processing of data cards).
      6. In order to ensure an adequate level of security it is required for shop the use of SSL certificates and use JS script provided by Espago.
      7. Example of a single payment:
        1. Fill the form by the client and initial validation of the parameters (done by the JS script in the client's browser)
        2. Creating a token and sending token_id to merchant's webapplication (implemented by JS script, token in the form of "cc_xxxxxxxxxx")
        3. Sending a payment request (request to /api/charges) from merchant's service (relying on token created in the user's browser and sent the form to you) and getting responce with confirmation/reason of rejection of the transaction.
      8. Information visible to the customer:
        1. If the client's profile has e-mail address, client receive notification e-mail each time he is charged. Notification contains information such as: company trade name, payment description and amount. 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 WARSAW PL" - so there is no information about the payment ID or payment description.
        3. 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
      9. 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.
    • 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 is a limit of compatibility:

      1. Payment form does not work correctly in Internet Explorer Version IE9 and older.
        • Script https://js.espago.com/v1 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.
        • 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.
    • 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 Recommended application/vnd.espago.v2+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. Choose Alt text button.
      5. Remember your AppID from menu "Service". Alt text
      6. Get the public key to create new token by the form. To see it (public key), click on the name of your service. Alt text
  • 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.

    While you are testing card payment solution you have to follow certain rules:

    1. At the test gateway you have to use the test card numbers. It is allowed to use only the test numbers, for example: '4242424242424242'
    2. During transaction completion through a test gateway should 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.
      The months and the results:
      a). 01-05 - transaction accepted
      b). 06 - transaction randomly accepted or rejected, it is very useful if you test the authorize function.
      c). 07-12 - transaction declined, for each month returns other reason.
    3. CVV/CVC code is ignored is test gateway.
    • Possible payment states


      StateDescription
      newNew payment, client's account has not been charged
      executedPayment 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.
      rejectedPayment was rejected.
      Notice: In response of the rejected transaction, you receive reject_reason parameter.
      failedPayment ended by failure
    • Possible reasons of payment rejection

      Information from "reject_reason" parameter

       

      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

       

      Details from "issuer_response_code" parameter

       

      Error code Meaning Proposed message
      00 Successful approval/completion Transaction approved, thank You!
      Rejected transaction - no response from issuer or incorrect card data REJECTED - Error. Please try again later.
      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,13,57,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 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.
      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 restricted, 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.
      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.

       

    • 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
      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
      amount Transaction Amount Decimal number such as 123.45
      currency Currency Three-character currency symbol in accordance with established service/MID
      description Description of Transaction It should contain 5-99 characters.

       

      Example of CURL

      curl -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"

      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"
      }
      The MO/TO transactions are also implemented in Espago Gateway. To enable MO/TO transaction, the moto parameter with true value has to be added to the sending new charge request. The default value of moto parameter is false, then the request is interpreted as a common new charge request.
    • 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.

      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 -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 can 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 -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 -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 -i https://sandbox.espago.com/api/charges -u app_id:password

      Example for CURL (with HTTP Parameters)

      curl -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",
            "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",
            "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_askKJSKKn880-j",
            "subscription":"sub_jqWaPgj1vgRa4k",
            "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, usually at 1am, so only until this time they could be reversed.

      Example for CURL

      curl -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

      (:id) - ID of selected Charge

      HTTP Parameters


      ParametersDescriptionRequired?Comments
      amountamount, that will be refundedNoThis 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.

      Example for CURL (without HTTP parameters)

      curl -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -X POST

      Example for CURL (with HTTP parameters)

      curl -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",
        "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",
        "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.

    • 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

      • New Plan

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

        HTTP Parameters
        ParameterDescriptionNotices
        period_unitperiod unitIt defines period of time between subsequent charges, for example: day or month.
        periodamount of periodsInteger number. It decides about amount of periods. Beetwen charges i.e. period_unit=month, period=2 will create charge every 2 months
        amountTransaction amountDecimal number, i.e. 123.45
        currencycurrencyCurrency symbol
        descriptionplan descriptionIt 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
        day1-366Plan, that charges client's card every specified number of days
        month1-12Plan that charges client's card every specified number of months
        Example for CURL
        curl -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 -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) -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!
        Only new subscriptions, which were made after updating plan data, will be charged with changed parameters.
        HTTP Parameters
        ParameterDescriptionNotices
        period_unitperiod unitIt defines period of time between charges, for example: day or month.
        periodamount of periodsInteger number. It decides about number of periods between charges.
        amountTransaction amountDecimal number, i.e. 123.45
        currencycurrencycurrency symbol
        descriptionplan descriptionIt should contain at least 5 characters.
        Examples of plans:
        Value of "period_unit"Acceptable values of "period"Result
        day1-366Plan, that charges client's card every specified number of days
        month1-12Plan 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 -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.

      Subscription is running since it is launched (it generat the first payment) until its stopped by the Merchant or until the failure of the payment (repeated three times or not repeated and if the stopping subscription in such a situation has been configured in the web panel).

      • 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
        ParameterDescriptionRequired?
        clientclient IDRequired
        planplan IDRequired
        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: Configuration). 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.

      • 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 -i https://sandbox.espago.com/api/subscriptions/(:id) -u app_id:password
        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
            }
          }]
        }
      • 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) -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


        ParametrsDescriptionRequired?Default settings
        pagePage numberNo1 (first page)
        perList of chargesNo25 (25 charges)
        clientSelected Client IDNoall clients
        Example CURL (without HTTP Parameters)
        curl -i https://sandbox.espago.com/api/subscriptions -u app_id:password
        Example CURL (with HTTP Parameters)
        curl -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


        ParametrsDescriptionRequired?Default settings
        pagePage numberNo1 (first page)
        perList of chargesNo25 (25 charges)
        clientSelected Client IDNoall clients
        Example CURL (without HTTP Parameters)
        curl -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:password
        Example CURL (with HTTP Parameters)
        curl -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 -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 fieldMeaningPossible values
        DatePlanned date of charge attemptTime in Unix Format
        PaidWas invoice paid?'True' or 'false'
        AttemptsNumber of executed attemptsInteger
        Next payment attemptData of execution next payment attemptTime 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 -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 -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 -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
        ParameterDescriptionField valueRequired?
        amountTransaction amountDecimal number, np. 123,45Required
        currencyCurrencyCurrency code in accordance with company MIDRequired
        clientClient IDid that allows you assign transaction to the clientRequired
        dateCharge dateDate of charge in unix time formatRequired
        descriptionTransaction descriptionDescription should contain at least 5 characters.Optional
        Example CURL
        curl -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 -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":"Item 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 -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 make possible to charge customer's card without storing any cardholder data i merchant's system.

    Tokens can be created automatically by Espago JS library. Below you can see the token usage schema. It is also described how tokens are created. In this chapter we also include an example form with useful tips how to integrate this form into merchant's system.

    • Token usage schema

      Alt text

      1. The payment form should be located at the Merchant site. Espago.js library has to be included. The site, where form will be located, must have in head section 'meta' tag with the Merchant public key. The card data from the form is used to create a token. The additional data is processed Merchant's system. The form must contain fields, which are listed below.
      2. The form comunicates with Espago Gateway via Espago.js library. In this step, request with customer card data is sent to Espago Gateway.
      3. Espago Gateway creates Token for valid data and sends it back to the form. In situation when wrong data was send, form is blocked.
      4. The token is sent to Merchant system in the 'card' parameter.
      5. The Merchant system can communicate with Espago Gateway, for example to create new customer with received token included as card data.
      6. The Espago Gateway sends response to request.
    • A sample form build with Espago.js library

      Here is a sample form built with Espago.js library. 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.

      Notice!
      In chapter preliminary-assumptions/useful-files in the download package there is available the latest example of the form using JS script with library jQuery.
      <html>
        <head>
          <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
      
          <script src="https://code.jquery.com/jquery-latest.js"></script>
          <script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.10.0/jquery.validate.js"></script>
          <script src='https://js.espago.com/v1/' type='text/javascript'></script>
          <script>
          $(document).ready(function(){
            $("#espago_form").submit(function(event){
              var espago = new Espago({public_key: 'public_key:', custom: true, live: false});
              event.preventDefault();
      
              if (espago.validate_card_number()){
                ///handling card number validation result communicates
                $("#espago_card_number_error").text("");
              } else {
                $("#espago_card_number_error").text("Wrong data!");
              };
      
              if (espago.validate_first_name()){
                ///handling first name validation result communicates
                $("#espago_first_name_error").text("");
              } else {
                $("#espago_first_name_error").text("Wrong data!");
              };
      
              if (espago.validate_last_name()){
                ///handling last name validation result communicates
                $("#espago_last_name_error").text("");
              } else {
                $("#espago_last_name_error").text("Wrong data!");
              };
      
              if (espago.validate_card_date()){
                ///handling expiration date validation result communicates
                $("#espago_year_error").text("");
              } else {
                $("#espago_year_error").text("Wrong data!");
              };
      
              if (espago.validate_card_cvc()){
                ///handling cvc code validation result communicates 
                $("#espago_verification_value_error").text("");
              } else {
                $("#espago_verification_value_error").text("Wrong data!");
              };
              espago.create_token();
            });
          });
          </script>
        </head>
        <body>
          <form id='espago_form' method='POST' action=''>
            <label>Credit Card Number</label>
            <input id='espago_card_number' type='text'/>
            <span id='espago_card_number_error'></span>
            <br />
            <label>First Name</label>
            <input id='espago_first_name' type='text'/>
            <span id='espago_first_name_error'></span>
            <br />
            <label>Last Name</label>
            <input id='espago_last_name' type='text'/>
            <span id='espago_last_name_error'></span>
            <br />
            <label>Month expire</label>
            <input id='espago_month' type='text'/>
            <span id='espago_month_error'></span>
            <br />
            <label>Year expire</label>
            <input id='espago_year' type='text'/>
            <span id='espago_year_error'></span>
            <br />
            <label>Verification Value</label>
            <input id='espago_verification_value' type='text'/>
            <span id='espago_verification_value_error'></span>
      
            <input type='submit' value='Go'/>
          </form>
        </body>
      </html> 
    • 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/v1/ is mandatory.

      The script must be downloaded by the client browser directly from the server Espago. Availability of script https://js.espago.com/v1/ (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/v1/ 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
    • Getting token's data

      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 -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]=2014" -d "card[month]=02" 

      Example response

      {
        "id":"cc_J_wDRKH6jmIEb_8",
        "created_at":1550871516,
        "used":false,
        "card":{
          "company":"VI",
          "last4":"4242",
          "year":2017,
          "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.

    • 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[first_name] Card owner name It's possible to create a new client without card data, but for clients with these information you should fill in all card's params.
      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 Available values: 01-12

       

      Notice:
      To save card's data it is necessary to send all required data (first and last name of owner, card number, card expiration year and month).

      Example for CURL

      curl -i https://sandbox.espago.com/api/clients -u app_id:password -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]=2014" -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":2017,
          "month":2,
          "first_name":"Jan",
          "last_name":"Kowalski",
          "authorized":true,
          "created_at":1381825758
        },
        "deleted":false
      }

      Description and possible values of paremeters authorized and company:

      Parameter Value Description
      company VI, MC Information about card company: VI - Visa, MC - MasterCard, AX - American Express
      authorized null, true, false Information about authoryzation, used logical values.
      null - authentication was not performed
      true - card authorization was successful
      false - card authorization was not successful
      created_at (number) Time in unix format
      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.
    • 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 -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

      Notice:
      If you update credit card data, you have to enter all the data (year, month and number of a card) even if you want to change only one of them. You may also use previously created card token.

      HTTP Parameters


      ParametersDescriptionComments
      descriptionShort customer descriptionShould have at least 5 characters.
      emailCustomer e-mail addressNot required, but necessary if Espago has to inform customer about changes of payments state via email.
      card[first_name]Card owner name
      card[last_name]Card owner surname
      card[number]Customer card number
      card[verification_value]CVV code
      card[year]Customer card expiration yearValue in format YYYY
      card[month]Customer card expiration monthAvailable values: 01-12

      Example for CURL

      curl -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]=2014" -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":2017,
          "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).
      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 -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


      ParametrsDescriptionRequired?Default settings
      pagePage numberNo1 (first page)
      perList of clientsNo25 (25 clients)

      Example for CURL (without HTTP Parameters)

      curl -i https://sandbox.espago.com/api/clients -u app_id:password

      Example for CURL (with HTTP Parameters)

      curl -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