-
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 on https://start.espago.com
-
Integration
- 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).
- 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).
- Webpanel with the ability to view and set parameters and viewing the test payments, queries and responces is available at https://sandbox.espago.com
- 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).
- After integrating to the production environment, test environment still remains available to the Merchant.
- 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.
- At download there are available sample files accelerating integration.
- The integration process consists of two stages:
-
General description of the gateway
- 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.
- An application URL address for a test environment is https://sandbox.espago.com/api
- An application architecture is compatible with REST standard.
- Initial data to Espago gateway should be send using HTTP PARAMS and the result data is returned in JSON format.
- 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).
- 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.
- Example of a single payment:
- Fill the form by the client and initial validation of the parameters (done by the JS script in the client's browser)
- Creating a token and sending token_id to merchant's webapplication (implemented by JS script, token in the form of "cc_xxxxxxxxxx")
- 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.
- Information visible to the customer:
- 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.
- 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.
- 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
- 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.
- All operations related to payments are carried out using the query to the API (Application Programming Interface).
-
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:
- 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.
- Payment form does not work correctly in Internet Explorer Version IE9 and older.
-
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:
- Choose
option. - Edit Service using
button. - 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.
- Choose
button. - Remember your AppID from menu "Service".
- Get the public key to create new token by the form. To see it (public key), click on the name of your service.
- Choose
-
-
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:
- At the test gateway you have to use the test card numbers. It is allowed to use only the test numbers, for example: '4242424242424242'
- 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. - CVV/CVC code is ignored is test gateway.
-
Possible payment states
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 -
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. -
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:passwordExample 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:passwordExample 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 GETExample 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 DELETEExample 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
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. Example for CURL (without HTTP parameters)
curl -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -X POSTExample for CURL (with HTTP parameters)
curl -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -d "amount=n" -X POSTExample 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:
- Choose option.
- Edit Service using button.
- 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
-
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.
-
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).
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.
- Choose
-
Plans
-
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 of time between subsequent charges, for example: day or month. period amount of periods Integer number. It decides about amount of periods. Beetwen charges i.e. 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 -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:passwordExample 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 DELETEResponse
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
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 PUTResponse
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:passwordExample 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
Parameter Description Required? client client ID Required plan plan ID Required 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:passwordExample 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 DELETEResponse
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 -i https://sandbox.espago.com/api/subscriptions -u app_id:passwordExample 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
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 -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:passwordExample 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:passwordExample 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 -i https://sandbox.espago.com/api/invoices/ -u app_id:passwordExample 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:passwordExample 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 POSTExample 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 -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:passwordExample 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 DELETEResponse
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
- 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.
- The form comunicates with Espago Gateway via Espago.js library. In this step, request with customer card data is sent to Espago Gateway.
- Espago Gateway creates Token for valid data and sends it back to the form. In situation when wrong data was send, form is blocked.
- The token is sent to Merchant system in the 'card' parameter.
- The Merchant system can communicate with Espago Gateway, for example to create new customer with received token included as card data.
- 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
Parameter Required? Default value Meaning public_key required Merchant public key live optional true If 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. form optional #espago_form Form name card_number optional #espago_card_number Customer's card number first_name optional #espago_first_name Card owner first name last_name optional #espago_last_name Card owner last name month optional #espago_month Month of card expiration date year optional #espago_year Year of card expiration date cvc optional #espago_verification_value Card Verifictaion number custom optional false "true" value allows to define parameters 'success' and 'error' by merchant willing. success optional function(data) {} A callback. Action inside this function will be executed when positive request is received. error optional function(data) {} A callback. Action inside this function will be executed when errors occurs. submit optional true Form confirmation and execution. -
Required form fields
Field ID Field Type Description espago_card_number text Customer's card number espago_first_name text First name on customer's card espago_last_name text Last name on customer's card espago_month text Card expiration month espago_year text Card expiration year espago_verification_value text Approval 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' valuevalidate_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' valuevalidate_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' valuevalidate_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' valuesvalidate_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 GETExample 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 successfulcreated_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 DELETEResponse
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:passwordExample 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
Parameters Description Comments description Short customer description Should have at least 5 characters. email Customer e-mail address Not 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 year Value in format YYYY card[month] Customer card expiration month Available 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 } -
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 -i https://sandbox.espago.com/api/clients -u app_id:passwordExample 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
-