specifications.contodeo.com
Open in
urlscan Pro
51.68.71.207
Public Scan
URL:
https://specifications.contodeo.com/
Submission: On March 22 via automatic, source certstream-suspicious — Scanned from FR
Submission: On March 22 via automatic, source certstream-suspicious — Scanned from FR
Form analysis 0 forms found in the DOM
Text Content
×
TOPICS
Introduction
OPERATIONS
HOW-TO Integrate
API Basics
Authentification
List pagination Management
Error Management
Versionning
Core functionnality
* Create a web transaction
* Create a web subscription
Transaction Maintenance
* Get transaction details
* Cancel an authorized transaction before the confirmation
* Make a refund based for a confirmed transaction
* Make the confirmation of an authorized transaction
* List transaction for a wallet / credit_card or merchand
Wallet
* Create a wallet
* Get the wallet list.
* Get wallet details.
* Desactivate the wallet.
Product
* Create a product
* List products for a merchand
* Get product details.
* Desactivate a product for futher subscription.
* Update a product
Plan
* Create a plan for recurring charge
* List plans for a merchand
* Get plan details.
* Delete the plan if not used.
* Update a plan
Subscription
* Get subscription details.
* Close subscription.
* Create a subscription
* List subscription for a wallet / credit card / product / plan / status for a
merchand
Charge
* List charges for a merchant
* Get charge details.
* Update charge details.
* Cancel the charge.
* List charges for a subscription
SCHEMA DEFINITIONS
Charge Creditcard Plan Product Subscription Transaction Wallet confirmRequest
createPlanRequest createProductRequest createSubscriptionRequest
updateChargeRequest updatePlanRequest updateProductRequest refundRequest
walletAuthorizeRequest walletCreationResponse webAuthorizeRequest
webSubscriptionRequest webResponse
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/api
PRODUCTION API ENDPOINT
https://contodeo.w-ha.com/contodeo/api
API 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 « : » :
* api_access_key
* timestamp
* version
* request body (could be empty in some cases).
A secret shared key (provided by W-HA) called “api_secret_key” is used to
compute the hash.
* StringToSign = api_access_key:timestamp:version:request_body
* Sign = HMAC-SHA256(StringToSign, api_secret_key)
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.
For 400 respons, complementary data are provided as json data when error are
encountred. An error code and a explanation on message is provided.
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.
Core functionnality
CREATE A WEB TRANSACTION
POST /transactions/init
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.
webAuthorizeRequest
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"
}
200 OK
webResponse
Parameters used for redirection or javascript integration
400 Bad Request
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"
}
Core functionnality
CREATE A WEB SUBSCRIPTION
POST /subscriptions/init
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.
webSubscriptionRequest
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"
}
200 OK
webResponse
Parameters used for redirection or javascript integration
400 Bad Request
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.
Transaction Maintenance
GET TRANSACTION DETAILS
GET /transactions/$id
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.
id: string
in query
The transaction id requested
200 OK
Transaction
Transaction details
400 Bad Request
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"
}
Transaction Maintenance
CANCEL AN AUTHORIZED TRANSACTION BEFORE THE CONFIRMATION
DELETE /transactions/$id
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.
id: string
in query
The identifier of the transaction to cancel
200 OK
Transaction
transaction details
type
Transaction
400 Bad Request
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"
}
Transaction Maintenance
MAKE A REFUND BASED FOR A CONFIRMED TRANSACTION
POST /transactions/$id/refund
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.
refundRequest
undefined
id: string
in query
The identifier of the transaction to refund
REQUEST CONTENT-TYPES: APPLICATION/JSON
REQUEST EXAMPLE
{
"amount": 12,
"external_id": "R-D12131321"
}
200 OK
Transaction
Detail of the refund transaction
type
Transaction
400 Bad Request
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"
}
Transaction Maintenance
MAKE THE CONFIRMATION OF AN AUTHORIZED TRANSACTION
POST /transactions/$id/confirm
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.
confirmRequest
undefined
id: string
in query
pass transaction id
REQUEST CONTENT-TYPES: APPLICATION/JSON
REQUEST EXAMPLE
{
"amount": 12
}
200 OK
Transaction
Detail of the Confirm transaction
type
Transaction
400 Bad Request
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"
}
Transaction Maintenance
LIST TRANSACTION FOR A WALLET / CREDIT_CARD OR MERCHAND
GET /transactions
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.
creditcard_id: string
in query
pass an optionnal creditcrad_id for looking up inventory
page: integer (int32) x ≥ 1
in query
request page number
per_page: integer (int32) 10 ≤ x ≤ 100
in query
number of records per page
status: enum
in query
filter the result by transaction status
type: enum
in query
Filer the result by transaction type.
wallet_id: string
in query
pass an optional wallet_id for looking up inventory
200 OK
Transaction
search results matching criteria
type
Transaction
400 Bad Request
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.
Wallet
CREATE A WALLET
POST /wallets
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.
200 OK
walletCreationResponse
Wallet Detail
type
walletCreationResponse
400 Bad Request
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"
}
Wallet
GET THE WALLET LIST.
GET /wallets
Get the wallet list filtered by status.
page: integer (int32) x ≥ 1
in query
request page number
per_page: integer (int32) 0 ≤ x ≤ 100
in query
number of records per page
status: enum
in query
Filter the search by wallet status
200 OK
Wallet
search results matching criteria
type
Wallet
400 Bad Request
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",
"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"
}
]
Wallet
GET WALLET DETAILS.
GET /wallets/$id
Get the wallet details with status and registered cards.
id: string
in query
pass wallet id
200 OK
Wallet
Wallet Detail
type
Wallet
400 Bad Request
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",
"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"
}
Wallet
DESACTIVATE THE WALLET.
DELETE /wallets/$id
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.
id: string
in query
pass wallet id
200 OK
Wallet
Wallet Detail
type
Wallet
400 Bad Request
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",
"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.
Product
CREATE A PRODUCT
POST /products
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.
createProductRequest
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"
}
200 OK
Product
Product details
type
Product
400 Bad Request
bad input parameter
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"
}
Product
LIST PRODUCTS FOR A MERCHAND
GET /products
List all products for this partners.
per_page: integer (int32) 10 ≤ x ≤ 100
in query
number of records per page
page: integer (int32) x ≥ 1
in query
request page number
200 OK
Product
search results matching criteria
type
Product
400 Bad Request
bad input parameter
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"
}
]
Product
GET PRODUCT DETAILS.
GET /products/$id
Get product details for the given identifier.
id: string
in query
The product id
200 OK
Product
Product Detail
type
Product
400 Bad Request
bad input parameter
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"
}
Product
DESACTIVATE A PRODUCT FOR FUTHER SUBSCRIPTION.
DELETE /products/$id
Disactivate the product with the given id, the product would not be available
for subscription anymore. A DISACTIVED product cannot be reactivated.
id: string
in query
the product id example 'hbo_access_eur_d290f1ee'
200 OK
Product
Product Details
type
Product
400 Bad Request
bad input parameter
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"
}
Product
UPDATE A PRODUCT
PUT /products/$id
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.
updateProductRequest
Pass the propertiers for product update
REQUEST CONTENT-TYPES: APPLICATION/JSON
REQUEST EXAMPLE
{
"external_id": "HBO_ACCESS_EUR",
"name": "HBO ACCESS",
"status": "ACTIVE"
}
200 OK
Product
Product details
type
Product
400 Bad Request
bad input parameter
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"
}
PLAN
The plan object is used to define a recurring payment periodicity. Plan and
product objects are used together to build subscriptions.
Plan
CREATE A PLAN FOR RECURRING CHARGE
POST /plans
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.
createPlanRequest
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"
}
200 OK
Plan
Plan detail
type
Plan
400 Bad Request
bad input parameter
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"
}
Plan
LIST PLANS FOR A MERCHAND
GET /plans
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.
page: integer (int32) x ≥ 1
in query
request page number
per_page: integer (int32) 10 ≤ x ≤ 100
in query
number of records per page
200 OK
Plan
search results matching criteria
type
Plan
400 Bad Request
bad input parameter
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"
}
]
Plan
GET PLAN DETAILS.
GET /plans/$id
Get plan details for the given identifier.
id: string
in query
pass plan id
200 OK
Plan
Plan Detail
type
Plan
400 Bad Request
bad input parameter
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"
}
Plan
DELETE THE PLAN IF NOT USED.
DELETE /plans/$id
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.
id: string
in query
pass plan id
200 OK
Plan
Plan Detail
type
Plan
400 Bad Request
bad input parameter
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"
}
Plan
UPDATE A PLAN
PUT /plans/$id
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.
updatePlanRequest
Pass the propertiers for plan update
REQUEST CONTENT-TYPES: APPLICATION/JSON
REQUEST EXAMPLE
{
"external_id": "illimited_monthly_billing",
"name": "Illimited monthly billing",
"status": "ACTIVE"
}
200 OK
Plan
Plan details
type
Plan
400 Bad Request
bad input parameter
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.
Subscription
GET SUBSCRIPTION DETAILS.
GET /subscriptions/$id
Return the subscription details.
id: string
in query
The subscription id
200 OK
Subscription
Subscription Detail
type
Subscription
400 Bad Request
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"
}
Subscription
CLOSE SUBSCRIPTION.
DELETE /subscriptions/$id
Desactivate the subscription, no later payment will be send. The pending charge
are also cancel. The is no way to reactivate a closed subscription.
id: string
in query
the subscription id
200 OK
Subscription
Subscription Detail
type
Subscription
400 Bad Request
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"
}
Subscription
CREATE A SUBSCRIPTION
POST /subscriptions
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.
createSubscriptionRequest
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"
}
200 OK
Subscription
Product details
type
Subscription
400 Bad Request
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"
}
Subscription
LIST SUBSCRIPTION FOR A WALLET / CREDIT CARD / PRODUCT / PLAN / STATUS FOR A
MERCHAND
GET /subscriptions
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.
creditcard_id: string
in query
pass an optional creditcard identifier for looking up inventory, the related
wallet identifier must be given
page: integer (int32) x ≥ 1
in query
request page number
per_page: integer (int32) 0 ≤ x ≤ 100
in query
number of records per page
plan_id: string
in query
pass an optional plan identifier for looking up inventory
product_id: string
in query
pass an optional product identifier for looking up inventory
status: enum
in query
Filter the search by subscription status
wallet_id: string
in query
pass an optional wallet identifier for looking up inventory
200 OK
Subscription
search results matching criteria
type
Subscription
400 Bad Request
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.
Charge
LIST CHARGES FOR A MERCHANT
GET /charges/
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.
page: integer (int32) x ≥ 1
in query
request page number
per_page: integer (int32) 10 ≤ x ≤ 100
in query
number of records per page
status: string NEW, PENDING, AUTHORIZED, CONFIRMED, CANCELLED, FAILED, SUSPENDED
in query
Status of the billing charge
200 OK
Charge
search results matching criteria
type
Charge
400 Bad Request
bad input parameter
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"
}
]
}
]
Charge
GET CHARGE DETAILS.
GET /charges/$id
Return details of the charge for the given id. The transaction related are
return as nested objects.
id: string
in query
pass charge id
200 OK
Charge
Charge Detail
type
Charge
400 Bad Request
bad input parameter
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"
}
]
}
Charge
UPDATE CHARGE DETAILS.
PUT /charges/$id
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.
updateChargeRequest
Pass the propertiers for charge update
REQUEST CONTENT-TYPES: APPLICATION/JSON
REQUEST EXAMPLE
{
"amount": 12,
"status": "PENDING"
}
200 OK
Charge
Charge Detail
type
Charge
400 Bad Request
bad input parameter
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"
}
]
}
Charge
CANCEL THE CHARGE.
DELETE /charges/$id
Cancel the future charge. The payment will not be done. The related subscription
is not closed.
id: string
in query
pass charge id
200 OK
Charge
Charge Detail
type
Charge
400 Bad Request
bad input parameter
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"
}
]
}
Charge
LIST CHARGES FOR A SUBSCRIPTION
GET /subscriptions/$subscriptionId/charges
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.
page: integer (int32) x ≥ 1
in query
request page number
per_page: integer (int32) 10 ≤ x ≤ 100
in query
number of records per page
subscriptionId: string
in query
pass subscription id for listing charge
status: string NEW, PENDING, AUTHORIZED, CONFIRMED, CANCELLED, FAILED, SUSPENDED
in query
Status of the billing charge
200 OK
Charge
search results matching criteria
type
Charge
400 Bad Request
bad input parameter
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"
}
CONFIRMREQUEST: OBJECT
amount: number x ≥ 0.01
EXAMPLE
{
"amount": 12
}
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"
}
Documentation by Spectacle