CONTODEO : A payment API by W-HA API Reference
This services goal is to provide a simple way to achiveve credit card paiement. The functionnality covered are :
- direct credit card paiement in an interractive way.
- credit card registration for merchant later uses
- subscription of recurring paiement
Test API Endpoint
https://test-contodeo.w-ha.com/contodeo/apiProduction API Endpoint
https://contodeo.w-ha.com/contodeo/apiAPI descriptor with doc
contodeo.yaml
Contact: support@contodeo.com
Schemes: https
Version: 1.0.0
HOW-TO Integrate
The design of the service attempt to be clear and simple as possible. The core purchase workflow is compound of two stages:
- transaction initiation
- display of purchase panel
Transaction initiation
The first stage is done between merchant and w-ha backend by a REST service call. This first call is necessary to define the purchase requirements (css framework, amount, currency, return Url) and to authenticate the merchant transaction. For security reasons all method calls are securised by a hash computation described in Authentification section. The initiation call delivers 3 informations :
- a unique payment token with a limited validity
- a service URL than can be use for javscript integration
- a direct payment url for redirect based integration
These informations will be necessary to establish the second stage, the display of purchase panel.
Display of purchase panel
The second stage of the workflow is to display the purchase form. There is two ways to achieve this:
- A simple redirection using the provided payment url, you can perform this with a server redirection or a client redirection. The credit card formulary will be the quiet simple default one using the specified css library. Field Labels and errors messages will be localized according to the language provided during the first stage.
- A direct integration in the page using the javascript library https://secure-cb.w-ha.com/secure-node-resources/js/secure-cb.min.js. With this solution you can finely tune the credit card formulary. You can make Look and feel customization like :
- change the titles colors
- change field labels
- change the display layout All this customization are directly described using html into the div injection target.
Display customisation
Here a simple integration example, that you can do to customize the display. Read the specific Customisation documentation for a complete informations:
...
<head>
<script src='https://secure-cb.w-ha.com/secure-node-resources/secure-cb.min.js'></script>
</head>
<body>
<script language='javascript'>
function injectIframe(){
SecureCb.injectIframe('template','${payment_url}','${payment_token}');
}
window.onload=injectIframe;
</script>
<div id='template'>
<label id='creditCardNumberLabel' for='creditCardNumber'>Credit card </label>
<label id='expirationDateLabel' for='expirationDate'>Expiration</label>
</div>
...
</body>
As you can see you need to provide the target div identifier in whitch the iframe will be injected. The ${payment_url} and ${payment_token} parameters are propagated form the transaction initiation response. The template div body can also be empty, for the example we put a customization of creditCard and expirationDate labels according with the predefined ids. You can have more details concerning the purchase form customization in the technical guide
http://documentations.contodeo.com
.
API Basics
The API is a RESTful Web Services with JSON formatted messages. Basicaly, it means that :
- Submiting new data is performed with HTTP POST request
- Retreiving existing data is performed with HTTP GET request
- Modifying existing data is performed with HTTP PUT request
- Removing or canceling existing data is performed with HTTP DELETE request
All requests must be sent with the HTTP header CONTENT-TYPE equals to "application/json"
Environnements
- Production environment: https://contodeo.w-ha.com
- Test / pre-production environment: https://test-contodeo.w-ha.com
- End-point : /contodeo/api/ Both environments use HTTPS standards with TLS 1.2. Details informations (certificats chain, supported cyphers list...) about our certificat can be be obtained through Qualys SSL Labs website https://www.ssllabs.com/ssltest
Authentification
All requests require to be fully authenticated through the HTTP header "Authorization". The content of the header should respect the format decribed below.
- All the requests must be sent from your server directly to our server and not from a user s browser or application.
- For security reasons, the API Access Key and Secret Key provided by W-HA must be stored securely in your server. It should never be accessible or visible to the end-users.
- It should not be stored or packaged in any source codes accessible from end-user point of view (html/javascript from a browser or in a source code of an application for Smartphone).
- The API Keys are accessible in your Dashboard in the Partner section.
Authorization header
AUTHORIZATION: AUTH API_ACCESS_KEY:TIMESTAMP:VERSION:SIGN
| Property | Type | Value | Description |
|---|---|---|---|
| api_access_key | string | size = 32 max | API Key (provided by W-HA) |
| timestamp | long | Should not be aged of more than 5 minutes. | Timestamp of the request in milliseconds |
| version | integer | Version number of the authentication process | |
| sign | string | HMAC-SHA256 signature |
| Signature computation |
|---|
The “sign” parameter is a HMAC-SHA256 of the following parameters separated by « : » :
A secret shared key (provided by W-HA) called “api_secret_key” is used to compute the hash.
|
Example with a request body
- api_access_key = OLqMu27t1mylpc2D
- api_secret_key = YMy7t54-WaF9F!LOSp994p1?0x8pUp
- timestamp = 1494862655078
- version = 1
- request_body = {"tag":"my_new_tag"}
- StringToSign = OLqMu27t1mylpc2D:1494862655078:1:{"tag":"my_new_tag"}
- Sign = 2b6cf86e9f3d5c50a5b7f79aa10c9ce6da1fcd31211bf87374347274c168cf01
HTTP Header
Authorization: AUTH OLqMu27t1mylpc2D:1494862655078:1:2b6cf86e9f3d5c50a5b7f79aa10c9ce6da1fcd31211bf87374347274c168cf01
Example with no request body
- api_access_key = OLqMu27t1mylpc2D
- api_secret_key = YMy7t54-WaF9F!LOSp994p1?0x8pUp
- timestamp = 1494862788453
- version = 1
- request_body =
- StringToSign = OLqMu27t1mylpc2D:1494862788453:1:
- Sign = 1e8b319599fa2185b55e502ed962490e9e23aceb920676e17c0ac76112d5450a
HTTP Header
Authorization: AUTH OLqMu27t1mylpc2D:1494862788453:1:1e8b319599fa2185b55e502ed962490e9e23aceb920676e17c0ac76112d5450a
List pagination Management
Some Web Services return a list of elements (i.e GET /transactions return a list of Transactions). Responses of these services are based on a pagination mechanism to control the number of returned elements. By default, the response is the first page and the maximum number of returned elements is 20. This behavior can be changed for a resquest by setting the following parameters :
| URL - Parameters | Type | Value | Description |
|---|---|---|---|
| page | integer | min = 1
optional, default = 1 |
Requested page index |
| per_page | integer | min = 1
max = 100 optional, default = 20 |
Maximum of element number per page |
The response HTTP body contains the list of elements and the response HTTP header includes the following properties:
| Header - Property | Type | Description |
|---|---|---|
| x-page | integer | Requested page index (equals to the request parameter page if it is set) |
| x-page-size | integer | Capacity for a page (equals to the request parameter per_page if it is set) |
| x-total-elements | long | The overall amount of elements corresponding to the search criteria (without pagination) |
| x-total-pages | integer | The number of pages corresponding to the search criteria |
Error Management
If a request failed, HTTP status code of the response is different of 200 (or associated 201, 204 ...) and the body contains an error object structuring the detailed cause of the problem.
HTTP error code
| Code | Description |
|---|---|
| 400 Bad request | See error code / message in response body. |
| 401 Authentication failure | Authentication failed. |
| 403 Forbidden | Authentication is OK but you are not authorized to access this method. |
| 404 Not found | Error on hostname or URI. |
| 405 Method not allowed | Wrong utilization of the method (e.g. GET instead of POST). |
| 500 The server encountered an unexpected condition | In case of internal error. |
| 501 Not Implemented | Not supported. |
| 503 Server busy and service unavailable | Service temporary unavailable. Try later. |
List of error code :
| Code | Explanation |
|---|---|
| AUTHORIZE_FAILURE | Returned when a authorization failed |
| CANCEL_FAILURE | Returned when a cancellation failed |
| CARD_DOES_NOT_EXIST | Returned when a request is send with a bad creditcard_id |
| CONFIRM_FAILURE | Returned when a confirmation failed |
| CHARGE_DOES_NOT_EXIST | Returned when a request is send with a bad charge_id |
| GENERIC_ERROR | Unclassified error |
| INVALID_STATUS | Returned when a operation is requested on an objet with a bad status |
| INVALID_DATA_ERROR | Returned when a request is received with bad data |
| OPERATION_NOT_ALLOWED | Returned when a request is send with a bad operation type (POST , GET ...) |
| PRODUCT_DOES_NOT_EXIST | Returned when a request is send with a bad product_id |
| PLAN_DOES_NOT_EXIST | Returned when a request is send with a bad plan_id |
| STATUS_DOES_NOT_EXIST | Returned when a request is send with a bad status |
| SUBSCRIPTION_DOES_NOT_EXIST | Returned when a request is send with a bad subscription_id |
| TECHNICAL_ERROR | Returned when a unexpected error occured |
| TRANSACTION_DOES_NOT_EXIST | Returned when a request is send with a bad transaction_id |
| TYPE_DOES_NOT_EXIST | Returned when a request is send with a bad type |
| REFUND_FAILURE | Returned when a refund failed |
| WALLET_DOES_NOT_EXIST | Returned when a request is send with a bad wallet_id |
| WALLET_INVALID_STATUS | Returned when a request is send on a wallet with a bad status |
Example
{ "code":"INVALID_DATA_ERROR", "message":"Invalid or inactive vad was provided" } Versionning
Versioning
Minor API modifications that are not breaking the compatibility with the existing API should be supported transparently by the partner. Example of non-breaking changes:
- adding new API endpoint/service
- adding some optional parameters in request header, query or body of existing API
- adding some optional new properties in the response header or body of existing API
- adding new possible values in ENUM parameters of a request
- changing the order of properties in a response
- changing human-readable strings such as error message
- changing size or format of generated ids (object identifier) but respecting the documented maximal size
Major API modifications breaking the compatibility will be managed through a new version number in the API URL. Example of breaking changes:
- renaming or removing existing endpoint/service
- renaming or adding mandatory parameters in the request header, query or body
- renaming or removing parameters in response header or body
- restricting allowed values of an ENUM in a request
Core functionnality
The main functionnality of the service is the transaction initiation. It is the mandatory function to initialize a web interractive purchase workflow. The first interractive workflow is need to register a card for later automatic payments. If the client accept to register his card it will be possible to bill without user validation. The payment will be done by REST call between backends servers, details are given in walletAuthorize section.
Create a web transaction
The webAuthorize is the first method to call for tansaction initiation. It is used to provide the purchase properties like amount, language or display conditionnal properties. The initiation return parameters needed to display the purchase panel. The purchase form can be display using a redirection ( from server side or client side) or by using the provided secure-cb.min.js library. In this case you have to provide the serviceUrl and the payment token parameters. There is tree kind of parameters to provide :
- purchase properties like amount, wallet_id, 3DS whitch lead the tool used to pay and the security level
- display properties like template (css framework used), language whitch modify the purchase look and feel
- conditionnal parameters whitch modify the behavior of the panel. For example wallet_registration accepts four values [ no, implicit, suggest, suggest_mandatory ]. In the first case 'no' the checkbox will not be displayed and the card will not be registered. The second case 'implicit' will not display the registration checkbox but the card will be registered (you must inform before the user in this case). The third case 'suggest' will display a optionnal checkbox. The last case 'suggest_mandatory' will display a checkbox that the user have to check.
All the usable parameters are listed and defined in the webAuthorizeRequest section.
Pass the propertiers for authorization creation
Request Content-Types: application/json
Request Example
{
"amount": 12,
"auto_confirm": false,
"creditcard_id": "WC-123343444",
"currency": "EUR",
"display_creditcard_list": true,
"external_id": "P-D12131321",
"language": "fr",
"mandatory_wallet_cvx": true,
"template": "bootstrap4",
"return_url": "https://achile-service.com/payment-return",
"skip_user_validation": false,
"wallet_id": "WA-d701748f0851",
"wallet_registration": "suggest"
}
Parameters used for redirection or javascript integration
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"payment_token": "AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4",
"payment_url": "https://secure-cb.w-ha.com/contodeo/purchaseForm",
"redirect_url": "https://secure-cb.w-ha.com/contodeo/purchaseForm?token=AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4"
}
Create a web subscription
The webSubscription method is used for subscription enrolment by defining the plan_id and product_id without preexisting wallet and card registered. Like webTransaction you can also provide optionnal properties like language, or display conditionnal properties. The initiation method return all parameters needed to display the purchase panel. The purchase form can be display using a redirection ( from server side or client side) or by using the provided secure-cb.min.js library. In this case you have to provide the serviceUrl and the payment token parameters. There is tree kind of parameters to provide :
- purchase properties like amount, wallet_id, 3DS whitch lead the tool used to pay and the security level
- display properties like template (css framework used), language whitch modify the purchase look and feel
- conditionnal parameters whitch modify the behavior of the panel. For example mandatory_cvx for preregistered card will display or not the cvx field. All the usable parameters are listed and defined in the webSubscriptionRequest section. The amount parameter is not mandatory such as the product already bring the information. It can used to apply a reduction on the first billing. The amount must be above zero. The subscription can also be achieved with an already registered card by calling subscription method. For subscription the amount parameter is not mandatory . If the amount parameter is provided it will replace the produt predefined price for this subscription.
Pass the propertiers for subscription creation
Request Content-Types: application/json
Request Example
{
"creditcard_id": "WC-123343444",
"display_creditcard_list": true,
"display_accept_subscription": true,
"external_id": "P-D12131321",
"language": "fr",
"mandatory_wallet_cvx": true,
"plan_id": "P-31FAD3-AEADA89-88377A",
"product_id": "P-c123dda-adcb5-de876",
"template": "bootstrap4",
"return_url": "https://achile-service.com/payment-return",
"skip_user_validation": false,
"wallet_id": "WA-d701748f0851"
}
Parameters used for redirection or javascript integration
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"payment_token": "AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4",
"payment_url": "https://secure-cb.w-ha.com/contodeo/purchaseForm",
"redirect_url": "https://secure-cb.w-ha.com/contodeo/purchaseForm?token=AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4"
}
Transaction Maintenance
The transaction maintenance facilities are used to manage transactions. For two stages tansactions, it's necessary to confirm de payment otherwise the authorization will expired and the client will not be debited. By default web transactions are done with autoconfirmation set to true. For two stages transactions you can cancel the authorization, no money would be debited.
Get transaction details
Return the transaction details by giving it's unique identifier. For interractive purchase, the transaction id is returned at the end of the purchase workflow as query parameter trx_id.
The transaction id requested
Transaction details
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
Cancel an authorized transaction before the confirmation
Cancelling an authorized transaction, is only usable before the confirmation. It's not available for autoconfirm transaction. A subscription transaction related can also be cancelled. For the first transaction of subscription (web workflow ) that will also cancel the subscription.
The identifier of the transaction to cancel
transaction details
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
Make a refund based for a confirmed transaction
The transaction refunding can only be used on a confirmed transaction. No refund can be done without a previous transaction. Several partials refunds may be done for one transaction payment, but the global sum of all refunds cannot be greater than the orignal transaction amount. Each refund will generate a refund transaction available on listing.
undefined
The identifier of the transaction to refund
Request Content-Types: application/json
Request Example
{
"amount": 12,
"external_id": "R-D12131321"
}
Detail of the refund transaction
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
Make the confirmation of an authorized transaction
The confirm function is used to confirm a already authorized transaction. It cannot be used on a transaction with autoconfirmation. The manual confirm can be used to do partial amount confirmation. Only one confirmation can be donne by transaction. Transaction authorized but not confirm will not debit the client.
undefined
pass transaction id
Request Content-Types: application/json
Request Example
{
"amount": 12
}
Detail of the Confirm transaction
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
List transaction for a wallet / credit_card or merchand
This function is used to list all transactions for a merchant / wallet or a credit card. If no parameter is given, it will list all transactions for a merchant. To list creditcard transactions you have to provide the creditcard_id. Bea carreful if you provided creditcard_id and wallet_id, the given wallet_id and creditcard_id must be related. The card have to be registered on the given wallet otherwise no result will be found. The transactions are ordered by creation date descending, the pagination mechanism is used to limit the result. Pagination properties are given in the header of response.
pass an optionnal creditcrad_id for looking up inventory
request page number
number of records per page
filter the result by transaction status
Filer the result by transaction type.
pass an optional wallet_id for looking up inventory
search results matching criteria
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
[
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
Wallet
The wallet object is used to register and group card for a given user. The management of wallet lets you consult/create/close a wallet on /wallet endPoint.
Create a wallet
Create an empty wallet, the result contains a wallet identifier to used for transaction initiation. For interractive authorize workflow , if no wallet id is given a new wallet is created to attached the payment card. Data to found the wallet are available into transaction details.
Wallet Detail
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"creation_date": "2016-08-29T09:12:33.001Z",
"status": "OPEN"
}
Get the wallet list.
Get the wallet list filtered by status.
request page number
number of records per page
Filter the search by wallet status
Response Content-Types: application/json
Response Example (200 OK)
[
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcards": [
{
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
}
],
"status": "OPEN"
}
]
Get wallet details.
Get the wallet details with status and registered cards.
pass wallet id
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcards": [
{
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
}
],
"status": "OPEN"
}
Desactivate the wallet.
Desactivate the wallet with the given identifier. The wallet with its registered cards would not be used anymore. A disactivated wallet cannot be reactivated. All subscription and pending charge attached to the wallet will also cancelled. No futher charge will be processed after the wallet closure.
pass wallet id
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcards": [
{
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
}
],
"status": "OPEN"
}
Product
The product object is used to memorize purchase properties like amount, currency or description with a signicant external identifier. The product model would be used to register a subscription.
Create a product
The product object is used to setup several datas ( like currency, amount , description) used to build recurring payment. The product can be disactivated by the merchant with an cancel call. The product creation result provide an identifier to use for subscription creation. The product is created with an ACTIVE status.
Pass the propertiers for product creation
Request Content-Types: application/json
Request Example
{
"amount": 12,
"currency": "EUR",
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
List products for a merchand
List all products for this partners.
number of records per page
request page number
Response Content-Types: application/json
Response Example (200 OK)
[
{
"id": "hbo_access_eur_d290f1ee",
"amount": 12,
"currency": "EUR",
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
]
Get product details.
Get product details for the given identifier.
The product id
Desactivate a product for futher subscription.
Disactivate the product with the given id, the product would not be available for subscription anymore. A DISACTIVED product cannot be reactivated.
the product id example 'hbo_access_eur_d290f1ee'
Update a product
This method allows to update a limited set of proprerties on a product. The status of a product can be changed from ACTIVE <-> INACTIVE. A product with a DISACTIVED status cannot be update.
Pass the propertiers for product update
Request Content-Types: application/json
Request Example
{
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
Plan
The plan object is used to define a recurring payment periodicity. Plan and product objects are used together to build subscriptions.
Create a plan for recurring charge
Create a recurring payment model. It's hightly recommended to used significant naming policy. For example a monthly recurring payment with illimited renewing will be ILLIMITED_MONTHY_BILLING. The number of payment charge is described by the charge_count parameter. Illimited recurring plan have a charge count to -1. For a time limited one year subscription with bi-week charging you will use the interval='WEEK' , interval_count=2 and charge_count=26 a good naming could be ONE_YEAR_BI_WEEK_BILLING.
Pass the propertiers for plan creation
Request Content-Types: application/json
Request Example
{
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "illimited_monthly_billing-90e6-111",
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
List plans for a merchand
List all plans for this partner, the result is ordered by creation_date descending. The pagination parameters are used to limit the result elements. Pagination properties are provided in response headers.
request page number
number of records per page
Response Content-Types: application/json
Response Example (200 OK)
[
{
"id": "illimited_monthly_billing-90e6-111",
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
]
Get plan details.
Get plan details for the given identifier.
pass plan id
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "illimited_monthly_billing-90e6-111",
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
Delete the plan if not used.
The cancel of plan can lead to it's removing if it is not used by a subscription. If the plan is used, it will be set on DISACTIVED status. It will be impossible to make a subscription using this plan.
pass plan id
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "illimited_monthly_billing-90e6-111",
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
Update a plan
This method allows to update a limited set of proprerties on a plan. The status of a plan can be changed from ACTIVE <-> INACTIVE. A plan with a DISACTIVED status cannot be update.
Pass the propertiers for plan update
Request Content-Types: application/json
Request Example
{
"external_id": "illimited_monthly_billing",
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "illimited_monthly_billing-90e6-111",
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
Subscription
Recurring paiement facilities are available througth subscriptions. There is two way to create a subscription:
- with the web authorize workflow envolving client and his acceptation
- with the subscription endpoint between backend on REST mode. For web subscriptions there is no need of pre-registered card, but the client have to accept the registration of a new one. The transaction of subscription have to be confirmed by the merchant. The direct subscription is only possible with already registred wallet and card. In this case there is no need of another service call, the subscription transaction is automatically confirm. A subscription is related to a payment tool, when the credit card expired the subscription is closed.
Get subscription details.
Return the subscription details.
The subscription id
Subscription Detail
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"cancel_date": "2019-10-01T09:12:33.001Z",
"creditcard_id": "WC-123343444",
"end_date": "2019-10-01T09:12:33.001Z",
"external_id": "M_TRX_0000001",
"id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"product_id": "hbo_access_eur_d290f1ee",
"plan_id": "illimited_monthly_billing-90e6-111",
"status": "ACTIVE",
"subscription_date": "2018-10-01T09:12:33.001Z",
"wallet_id": "WA-d701748f0851"
}
Close subscription.
Desactivate the subscription, no later payment will be send. The pending charge are also cancel. The is no way to reactivate a closed subscription.
the subscription id
Subscription Detail
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"cancel_date": "2019-10-01T09:12:33.001Z",
"creditcard_id": "WC-123343444",
"end_date": "2019-10-01T09:12:33.001Z",
"external_id": "M_TRX_0000001",
"id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"product_id": "hbo_access_eur_d290f1ee",
"plan_id": "illimited_monthly_billing-90e6-111",
"status": "ACTIVE",
"subscription_date": "2018-10-01T09:12:33.001Z",
"wallet_id": "WA-d701748f0851"
}
Create a subscription
Create a subscription with recurring payment according to charging plan et product. The first payment is sent at subscrption creation. The subscription is registered only if the first payment is authorized. With backends call there is no need to confirm the first authorized transaction to confirm the subscription.
Pass the propertiers for subscription creation
Request Content-Types: application/json
Request Example
{
"creditcard_id": "WC-123343444",
"external_id": "M_TRX_0000001",
"plan_id": "illimited_monthly_billing-90e6-111",
"product_id": "hbo_access_eur_d290f1ee",
"wallet_id": "WA-d701748f0851"
}
Product details
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
{
"cancel_date": "2019-10-01T09:12:33.001Z",
"creditcard_id": "WC-123343444",
"end_date": "2019-10-01T09:12:33.001Z",
"external_id": "M_TRX_0000001",
"id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"product_id": "hbo_access_eur_d290f1ee",
"plan_id": "illimited_monthly_billing-90e6-111",
"status": "ACTIVE",
"subscription_date": "2018-10-01T09:12:33.001Z",
"wallet_id": "WA-d701748f0851"
}
List subscription for a wallet / credit card / product / plan / status for a merchand
List all subscriptions for this partners according with the given parameter. If no parameter are sent all the subscription for this merchant are returned. If wallet and creditcard_id parameters are used together, the creditcard must be registered on the given wallet. All parameters can be used together, the result elements will be limited according to pagination parameter. The result will be ordered by creation date descending with pagination properties in header.
pass an optional creditcard identifier for looking up inventory, the related wallet identifier must be given
request page number
number of records per page
pass an optional plan identifier for looking up inventory
pass an optional product identifier for looking up inventory
Filter the search by subscription status
pass an optional wallet identifier for looking up inventory
search results matching criteria
bad input parameter
Response Content-Types: application/json
Response Example (200 OK)
[
{
"cancel_date": "2019-10-01T09:12:33.001Z",
"creditcard_id": "WC-123343444",
"end_date": "2019-10-01T09:12:33.001Z",
"external_id": "M_TRX_0000001",
"id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"product_id": "hbo_access_eur_d290f1ee",
"plan_id": "illimited_monthly_billing-90e6-111",
"status": "ACTIVE",
"subscription_date": "2018-10-01T09:12:33.001Z",
"wallet_id": "WA-d701748f0851"
}
]
Charge
The charge are used to planify the recurring payment related to a subscription. Charges are established according to the plan and the product. Charges are built several days before the subscription renewal. A charge can be cancelled before the payment. Charges can be listed to have a payment history for a given subscription. A charge create a transaction to order a payment, if payment authorization fails, the charge will failed after 3 attempts. A charge can be modified by the merchant to apply a reduction or cancelled a payment. A charge can be relaunch by the merchant with an update operation. There no need for the merchant to confirm automatic transaction.
List charges for a merchant
The list charges return all charges for a merchant, result elements can be filter by status. They are limited by pagination parameters. Pagination properties are given into response header.
request page number
number of records per page
Status of the billing charge
Response Content-Types: application/json
Response Example (200 OK)
[
{
"date_created": "2018-10-01T09:12:33.001Z",
"id": "illimited_monthly_billing-90e6-111",
"amount": 12,
"currency": "EUR",
"payment_date": "2018-10-01T09:12:33.001Z",
"send_date": "2018-10-01T09:12:33.001Z",
"status": "PENDING",
"subscription_id": "s-1212_13313_131331",
"transactions": [
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
}
]
Get charge details.
Return details of the charge for the given id. The transaction related are return as nested objects.
pass charge id
Response Content-Types: application/json
Response Example (200 OK)
{
"date_created": "2018-10-01T09:12:33.001Z",
"id": "illimited_monthly_billing-90e6-111",
"amount": 12,
"currency": "EUR",
"payment_date": "2018-10-01T09:12:33.001Z",
"send_date": "2018-10-01T09:12:33.001Z",
"status": "PENDING",
"subscription_id": "s-1212_13313_131331",
"transactions": [
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
}
Update charge details.
Update the charge amount or status. Update amount can only be done on a charge with status [NEW,PENDING, FAILED]. A suspended or failed charge can be relaunch with an update with pending status. It is possible to update a charge using status ['PENDING','SUSPENDED','CANCELLED']. A cancelled charge cannot be relaunch.
Pass the propertiers for charge update
Request Content-Types: application/json
Request Example
{
"amount": 12,
"status": "PENDING"
}
Response Content-Types: application/json
Response Example (200 OK)
{
"date_created": "2018-10-01T09:12:33.001Z",
"id": "illimited_monthly_billing-90e6-111",
"amount": 12,
"currency": "EUR",
"payment_date": "2018-10-01T09:12:33.001Z",
"send_date": "2018-10-01T09:12:33.001Z",
"status": "PENDING",
"subscription_id": "s-1212_13313_131331",
"transactions": [
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
}
Cancel the charge.
Cancel the future charge. The payment will not be done. The related subscription is not closed.
pass charge id
Response Content-Types: application/json
Response Example (200 OK)
{
"date_created": "2018-10-01T09:12:33.001Z",
"id": "illimited_monthly_billing-90e6-111",
"amount": 12,
"currency": "EUR",
"payment_date": "2018-10-01T09:12:33.001Z",
"send_date": "2018-10-01T09:12:33.001Z",
"status": "PENDING",
"subscription_id": "s-1212_13313_131331",
"transactions": [
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
}
List charges for a subscription
The list charges return all charges for a given subscription. The result are return ordered by creation date descending. Result elements can be filter by status. They are limited by pagination parameters. Pagination properties are given into response header.
request page number
number of records per page
pass subscription id for listing charge
Status of the billing charge
Response Content-Types: application/json
Response Example (200 OK)
[
{
"date_created": "2018-10-01T09:12:33.001Z",
"id": "illimited_monthly_billing-90e6-111",
"amount": 12,
"currency": "EUR",
"payment_date": "2018-10-01T09:12:33.001Z",
"send_date": "2018-10-01T09:12:33.001Z",
"status": "PENDING",
"subscription_id": "s-1212_13313_131331",
"transactions": [
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
}
]
Schema Definitions
Charge: object
- date_created: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
Date of creation of charge
- id: string (uuid)
-
The unique charge identifier use in requests
- amount: number x ≥ 0.01
-
The amount of the charge
- currency: string EUR, PLN, GBP, DKK, SEK, NOK, CHF, RON
-
The currency for this charge
- payment_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
The date when the payment has succeed. Only feeled if payment has succeed.
- send_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
the date when the payment will be done.
- status: string NEW, PENDING, AUTHORIZED, CONFIRMED, CANCELLED, FAILED, SUSPENDED
-
Status of the billing charge
- subscription_id: string
-
The subscription id related to this charge
- transactions: Transaction
-
Transaction
Example
{
"date_created": "2018-10-01T09:12:33.001Z",
"id": "illimited_monthly_billing-90e6-111",
"amount": 12,
"currency": "EUR",
"payment_date": "2018-10-01T09:12:33.001Z",
"send_date": "2018-10-01T09:12:33.001Z",
"status": "PENDING",
"subscription_id": "s-1212_13313_131331",
"transactions": [
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
]
}
Creditcard: object
- brand: string VISA, MASTERCARD, CB
-
credit card status
- creation_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
- expiry_date: string (MM/YYYY)
-
Credit card expiration date
- id: string (uuid)
- pan: string
-
Offusced Pan
- status: string VALIDATED, EXPIRED, SUSPENDED, BLOCKED
-
credit card status
Example
{
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
}
Plan: object
- id: string (uuid)
-
Unique identifier used to take subscription
- charge_count: number x ≥ -1
-
The number charges that will be established. -1 stand for illimited charges.
- external_id: string
-
Merchant significant identifier
- interval: string DAY, WEEK, MONTH
-
Define the billing period unit
- interval_count: number 1 ≤ x ≤ 52
-
The number of interval between two billing
- name: string
-
Merchant convenience name
- status: string ACTIVE, INACTIVE, DISACTIVATED
-
Status of the plan
Example
{
"id": "illimited_monthly_billing-90e6-111",
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
Product: object
- id: string (uuid)
-
Unique product identifier use to make subscription
- amount: number x ≥ 0.01
-
The amount of the product
- currency: string EUR, PLN, GBP, DKK, SEK, NOK, CHF, RON
-
The device of billing
- external_id: string
-
Merchant convenience identifier
- name: string
-
Merchant convenience name
- status: string ACTIVE, INACTIVE, DISACTIVATED
-
Status of the product
Example
{
"id": "hbo_access_eur_d290f1ee",
"amount": 12,
"currency": "EUR",
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
Subscription: object
- cancel_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
Date of cancellation
- creditcard_id: string (uuid)
-
The identifier of the creditcard used to subscribe
- end_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
The planned endDate for limited recurring plan. Void if unlimited
- external_id: string (uuid)
-
Option externalID given by the merchant. Not used by the system.
- id: string (uuid)
-
The unique subscription identifier generate by service
- product_id: string (uuid)
-
The product identifier recurrely billed
- plan_id: string (uuid)
-
The plan identifier whitch describes the billing frequency
- status: string NEW, ACTIVE, TERMINATION_PENDING, TERMINATED, CANCELLED
- subscription_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
Subscription date
- wallet_id: string (uuid)
-
The identifier of wallet involve for the subscription
Example
{
"cancel_date": "2019-10-01T09:12:33.001Z",
"creditcard_id": "WC-123343444",
"end_date": "2019-10-01T09:12:33.001Z",
"external_id": "M_TRX_0000001",
"id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"product_id": "hbo_access_eur_d290f1ee",
"plan_id": "illimited_monthly_billing-90e6-111",
"status": "ACTIVE",
"subscription_date": "2018-10-01T09:12:33.001Z",
"wallet_id": "WA-d701748f0851"
}
Transaction: object
- amount: number x ≥ 0.01
- authorization_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
- authorization_timeout_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
- creation_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
- creditcard: Creditcard
- currency: string EUR, PLN, GBP, DKK, SEK, NOK, CHF, RON
- external_id: string (uuid)
-
Option externalID given by the merchant. Not used by the system.
- id: string (uuid)
- status: string NEW, CANCELLED, FAILED, CONFIRMED, AUTHORIZED, EXPIRED
- subscription_id: string (uuid)
- type: object PAYMENT, REFUND
- wallet_id: string (uuid)
Example
{
"amount": 10,
"authorization_date": "2016-08-29T09:12:33.001Z",
"authorization_timeout_date": "2016-08-29T09:12:33.001Z",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcard": {
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
},
"currency": "EUR",
"external_id": "M_TRX_0000001",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"status": "CONFIRMED",
"subscription_id": "illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851",
"type": "PAYMENT",
"wallet_id": "WA-d701748f0851"
}
Wallet: object
- id: string (uuid)
-
The unique identifier used to reference this wallet during payment
- creation_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
Wallet creation date
- creditcards: Creditcard
-
list of creditcard attached at this wallet
-
Creditcard - status: string OPEN, DISACTIVATED
-
The wallet status
Example
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"creation_date": "2016-08-29T09:12:33.001Z",
"creditcards": [
{
"brand": "VISA",
"creation_date": "2016-08-29T09:12:33.001Z",
"expiry_date": "01/2019",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"pan": "4000 XXXX XXXX XXXX",
"status": "VALIDATED"
}
],
"status": "OPEN"
}
createPlanRequest: object
- charge_count: number x ≥ -1
-
The max number of charge to proceed. -1 is used to refer a illimited renewal. Values below -1 and 0 are forbidden.
- external_id: string
-
merchant significant identifier
- interval: string DAY, WEEK, MONTH
-
Define the billing interval unit
- interval_count: number 1 ≤ x ≤ 52 1
-
The number of interval between two blling
- name: string
-
Merchant convenience name
- status: string ACTIVE, INACTIVE
-
Status of the plan
Example
{
"charge_count": -1,
"external_id": "illimited_monthly_billing",
"interval": "MONTH",
"interval_count": 1,
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
createProductRequest: object
- amount: number x ≥ 0.01
-
The amount of the product
- currency: string EUR, PLN, GBP, DKK, SEK, NOK, CHF, RON
-
The device of billing
- external_id: string
-
Merchant convenience identifier
- name: string
-
Merchant convenience name
- status: string ACTIVE, INACTIVE
-
Status of the product
Example
{
"amount": 12,
"currency": "EUR",
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
createSubscriptionRequest: object
- creditcard_id: string (uuid)
-
The identifier of the creditcard used to subscribe
- external_id: string (uuid)
-
Option externalID given by the merchant. Not used by the system.
- plan_id: string (uuid)
-
The plan identifier whitch describes the billing frequency
- product_id: string (uuid)
-
The product identifier that will be recurrely billed
- wallet_id: string (uuid)
-
The identifier of wallet involve for the subscription
Example
{
"creditcard_id": "WC-123343444",
"external_id": "M_TRX_0000001",
"plan_id": "illimited_monthly_billing-90e6-111",
"product_id": "hbo_access_eur_d290f1ee",
"wallet_id": "WA-d701748f0851"
}
updateChargeRequest: object
- amount: number x ≥ 0.01
-
The amount of the charge
- status: string PENDING, CANCELLED, SUSPENDED
-
Status of the billing charge
Example
{
"amount": 12,
"status": "PENDING"
}
updatePlanRequest: object
- external_id: string
-
merchant significant identifier
- name: string
-
Merchant convenience name
- status: string ACTIVE, INACTIVE
-
Status of the plan
Example
{
"external_id": "illimited_monthly_billing",
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
updateProductRequest: object
- external_id: string
-
Merchant convenience identifier
- name: string
-
Merchant convenience name
- status: string ACTIVE, INACTIVE
-
Status of the product
Example
{
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
refundRequest: object
- amount: number x ≥ 0.01
- external_id: string (uuid)
Example
{
"amount": 12,
"external_id": "R-D12131321"
}
walletAuthorizeRequest: object
- amount: number x ≥ 0.01
-
The amount of payment
- creditcard_id: string (uuid)
-
The credit card on whitch the payment will be done.
- currency: string EUR, PLN, GBP, DKK, SEK, NOK, CHF, RON
-
The currency for this authorize, if not given the default merchant currency is used
- external_id: string (uuid)
-
Option externalID given by the merchant. Not used by the system.
- wallet_id: string (uuid)
-
The wallet to use for payment
Example
{
"amount": 12,
"creditcard_id": "WC-123343444",
"currency": "EUR",
"external_id": "M_TRX_0000001",
"wallet_id": "WA-d701748f0851"
}
walletCreationResponse: object
- id: string (uuid)
-
The unique identifier used to reference this wallet during payment
- creation_date: string (yyyy-MM-dd'T'HH:mm:ss'Z')
-
Wallet creation date
- status: string OPEN, DISACTIVATED
-
The wallet status
Example
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"creation_date": "2016-08-29T09:12:33.001Z",
"status": "OPEN"
}
webAuthorizeRequest: object
- amount: number x ≥ 0.01
-
Amount of the payment
- auto_confirm: boolean true
-
Specify if the payment will be done in two steps (authorize/confirm) with merchant interaction, by defaut the confirmation is done asynchronously automatically.
- creditcard_id: string (uuid)
-
The credit card on whitch the payment will be done, the client will not be able to choose another card. This parameter must be used with display_credicard_list:true.
- currency: string EUR, PLN, GBP, DKK, SEK, NOK, CHF, RON
-
The currency for this authorize, if not given the default merchant currency is used
- display_creditcard_list: boolean false
-
Choose to display the already registered and valid credit card
- external_id: string (uuid)
-
The merchant payment reference, unicity will not be checked.
- language: string da, de, en, es, fi, fr, it, nl, no, pl, pt, ro, sk, sv Browser language detection or english if language not available
-
Language ISO code of the payment panel :
- en → english
- fr → french
- fi → finnish
- de → dutch
- it → italian
- pl → polish
- es → spanish
- da → danish
- pt → portuguese
- no → norwegian
- ro → romanian
- sk → slovak
- sv → swedish
- mandatory_wallet_cvx: boolean true
-
Choose to ask creditcard cvx for wallet interractive payment.
- template: string skeleton, bootstrap4, boosted bootstrap4
-
The css framework to use to display, by default the bootstrap template will be used.
- return_url: string
-
The return url used at the end of purchase workflow to notify the merchant if payment succeed or not.
- skip_user_validation: boolean false
-
Choose to skip user validation, only usable with a preselected card 'creditcard_id' and 'mandatory_wallet_cvx' at false. The property 3DS with 'mandatory' or 'managed' values with lead to display the bank 3DS panel. If 3DS as 'none' value the authorize will be done automatically without user inpout. This kind of authorize id not efficient. The direct wallet purchase using /transactions service directly is prefarable.
- wallet_id: string (uuid)
-
The wallet_id on whitch the card will be registered if the client accept the registration. If the client have registered is card and a wallet_id is not given, a new wallet is created and the identifier will be available on transaction details.
- wallet_registration: string no, implicit, suggest, suggest_mandatory no
-
Choose to suggest card memorize to user, the card will be register on the given wallet_id
Example
{
"amount": 12,
"auto_confirm": false,
"creditcard_id": "WC-123343444",
"currency": "EUR",
"display_creditcard_list": true,
"external_id": "P-D12131321",
"language": "fr",
"mandatory_wallet_cvx": true,
"template": "bootstrap4",
"return_url": "https://achile-service.com/payment-return",
"skip_user_validation": false,
"wallet_id": "WA-d701748f0851",
"wallet_registration": "suggest"
}
webSubscriptionRequest: object
- creditcard_id: string (uuid)
-
The credit card on whitch the payment will be done, the client will not be able to choose another card. This parameter must be used with display_credicard_list:true.
- display_creditcard_list: boolean false
-
Choose to display the already registered and valid credit card
- display_accept_subscription: boolean true
-
In a subscription case choose if an enforced subscription acceptation checkbox have to be displayed. By default the checkbox is displayed below the wallet registration checkbox for new card. Usage of this parameter is restricted to selected merchant.
- external_id: string (uuid)
-
The merchant payment reference, unicity will not be checked.
- language: string da, de, en, es, fi, fr, it, nl, no, pl, pt, ro, sk, sv Browser language detection or english if language not available
-
Language ISO code of the payment panel :
- en → english
- fr → french
- de → dutch
- it → italian
- fi → finnish
- pl → polish
- es → spanish
- da → danish
- pt → portuguese
- no → norwegian
- ro → romanian
- sk → slovak
- sv → swedish
- mandatory_wallet_cvx: boolean true
-
Choose to ask creditcard cvx for wallet interractive payment.
- plan_id: string (uuid)
-
The recurring plan used to charge the subscription.
- product_id: string (uuid)
-
The product to bill and subscribe with the given billing plan. Only used for recurring subscription.
- template: string skeleton, bootstrap4, boosted bootstrap4
-
The css framework to use to display, by default the bootstrap template will be used.
- return_url: string
-
The return url used at the end of purchase workflow to notify the merchant if payment succeed or not.
- skip_user_validation: boolean false
-
Choose to skip user validation, only usable with a preselected card 'creditcard_id' and 'mandatory_wallet_cvx' at false. The property 3DS with 'mandatory' or 'managed' values with lead to display the bank 3DS panel. If 3DS as 'none' value the authorize will be done automatically without user inpout. This kind of authorize id not efficient. The direct wallet purchase using /transactions service directly is prefarable.
- wallet_id: string (uuid)
-
The wallet_id on whitch the card will be registered if the client accept the registration. If the client have registered is card and a wallet_id is not given, a new wallet is created and the identifier will be available on transaction details.
Example
{
"creditcard_id": "WC-123343444",
"display_creditcard_list": true,
"display_accept_subscription": true,
"external_id": "P-D12131321",
"language": "fr",
"mandatory_wallet_cvx": true,
"plan_id": "P-31FAD3-AEADA89-88377A",
"product_id": "P-c123dda-adcb5-de876",
"template": "bootstrap4",
"return_url": "https://achile-service.com/payment-return",
"skip_user_validation": false,
"wallet_id": "WA-d701748f0851"
}
webResponse: object
- payment_token: string
-
A token to provide to the payment service to include the payment panel (see Credit Card Payment Panel)
- payment_url: string
-
The URL of the payment service to include the payment panel (see Credit Card Payment Panel)
- redirect_url: string
-
URL of the payment panel where the partner should redirect the user to perform payment authorization.
Example
{
"payment_token": "AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4",
"payment_url": "https://secure-cb.w-ha.com/contodeo/purchaseForm",
"redirect_url": "https://secure-cb.w-ha.com/contodeo/purchaseForm?token=AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4"
}