swagger: '2.0' info: title: ' CONTODEO : A payment API by W-HA' version: 1.0.0 description: ' 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 You can find here the json description of the service. ' # put the contact info for your development or API team contact: email: support@contodeo.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html # tags are used for organizing operations tags: - name: HOW-TO Integrate description: " 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**. " - name: API Basics description : ' 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 ' - name : Authentification description : ' 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
PropertyTypeValueDescription
api_access_keystringsize = 32 maxAPI Key (provided by W-HA)
timestamplongShould not be aged of more than 5 minutes.Timestamp of the request in milliseconds
versionintegerVersion number of the authentication process
signstringHMAC-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 ' - name: List pagination Management description: ' 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 - ParametersTypeValueDescription
pageintegermin = 1
optional, default = 1		Requested page index
per_pageintegermin = 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 - PropertyTypeDescription
x-pageinteger Requested page index (equals to the request parameter page if it is set)
x-page-sizeintegerCapacity for a page (equals to the request parameter per_page if it is set)
x-total-elementslongThe overall amount of elements corresponding to the search criteria (without pagination)
x-total-pagesintegerThe number of pages corresponding to the search criteria
' - name: Error Management description: ' 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 ###
CodeDescription
400 Bad requestSee error code / message in response body.
401 Authentication failureAuthentication failed.
403 ForbiddenAuthentication is OK but you are not authorized to access this method.
404 Not foundError on hostname or URI.
405 Method not allowedWrong utilization of the method (e.g. GET instead of POST).
500 The server encountered an unexpected conditionIn case of internal error.
501 Not ImplementedNot supported.
503 Server busy and service unavailableService 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 :
CodeExplanation
AUTHORIZE_FAILUREReturned when a authorization failed
CANCEL_FAILUREReturned when a cancellation failed
CARD_DOES_NOT_EXISTReturned when a request is send with a bad creditcard_id
CONFIRM_FAILUREReturned when a confirmation failed
CHARGE_DOES_NOT_EXISTReturned when a request is send with a bad charge_id
GENERIC_ERRORUnclassified error
INVALID_STATUSReturned when a operation is requested on an objet with a bad status
INVALID_DATA_ERRORReturned when a request is received with bad data
OPERATION_NOT_ALLOWEDReturned when a request is send with a bad operation type (POST , GET ...)
PRODUCT_DOES_NOT_EXISTReturned when a request is send with a bad product_id
PLAN_DOES_NOT_EXISTReturned when a request is send with a bad plan_id
STATUS_DOES_NOT_EXISTReturned when a request is send with a bad status
SUBSCRIPTION_DOES_NOT_EXISTReturned when a request is send with a bad subscription_id
TECHNICAL_ERRORReturned when a unexpected error occured
TRANSACTION_DOES_NOT_EXISTReturned when a request is send with a bad transaction_id
TYPE_DOES_NOT_EXISTReturned when a request is send with a bad type
REFUND_FAILUREReturned when a refund failed
WALLET_DOES_NOT_EXISTReturned when a request is send with a bad wallet_id
WALLET_INVALID_STATUSReturned when a request is send on a wallet with a bad status
Example
{ "code":"INVALID_DATA_ERROR", "message":"Invalid or inactive vad was provided" } ' - name: Versionning description: ' ### 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 ' - name: Core functionnality description: " 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. " - name: Transaction Maintenance description: " 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. " - name : Wallet description : " 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. " - name : Product description : " 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. " - name : Plan description : " The plan object is used to define a recurring payment periodicity. Plan and product objects are used together to build subscriptions. " - name : Subscription description: " 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. " - name : Charge description : " 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. " paths: # /transactions: # post: # tags: # - Transaction Maintenance # summary: Create a server to server authorization based on wallet_id and creditCard_id # operationId: walletAuthorize # description: # "Create a authorization based on wallet_id/Creditcard_id, this function is only used for direct payment not for subscription. # The creditcard_id must be registered with the given wallet_id. The operation return the transaction details with its status. # The transaction must be confirmed with a later confirm call. # " # consumes: # - application/json # produces: # - application/json # parameters: # - in: body # name: walletAuthorize # description: Pass the propertiers for authorization creation # schema: # $ref: '#/definitions/walletAuthorizeRequest' # responses: # 200: # description: transaction details # schema: # $ref: '#/definitions/Transaction' # 400: # description: bad input parameter /transactions/init: post: tags: - Core functionnality summary: Create a web transaction operationId: webAuthorize description: " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: webAuthorize description: Pass the propertiers for authorization creation schema: $ref: '#/definitions/webAuthorizeRequest' responses: 200: description: Parameters used for redirection or javascript integration schema: $ref: '#/definitions/webResponse' 400: description: bad input parameter /transactions/$id: get: tags: - Transaction Maintenance summary: Get transaction details operationId: getTransaction description: "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." produces: - application/json parameters: - in: query name: id description: "The transaction id requested" required: true type: string responses: 200: description: Transaction details schema: $ref: '#/definitions/Transaction' 400: description: bad input parameter delete: tags: - Transaction Maintenance summary: Cancel an authorized transaction before the confirmation description: "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." produces: - application/json parameters: - in: query name: id description: "The identifier of the transaction to cancel" required: true type: string responses: 200: description: transaction details schema: type: object $ref: '#/definitions/Transaction' 400: description: bad input parameter /transactions/$id/refund: post: tags: - Transaction Maintenance summary: Make a refund based for a confirmed transaction operationId: refund description: "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." consumes: - application/json produces: - application/json parameters: - in: query name: id description: "The identifier of the transaction to refund" required: true type: string - in: body name : refundRequest schema: $ref: '#/definitions/refundRequest' responses: 200: description: Detail of the refund transaction schema: type: object $ref: '#/definitions/Transaction' 400: description: bad input parameter /transactions/$id/confirm: post: tags: - Transaction Maintenance summary: Make the confirmation of an authorized transaction operationId: confirm description: "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." consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass transaction id required: true type: string - in: body name : refundRequest schema: $ref: '#/definitions/confirmRequest' responses: 200: description: Detail of the Confirm transaction schema: type: object $ref: '#/definitions/Transaction' 400: description: bad input parameter /transactions: get: tags: - Transaction Maintenance summary: List transaction for a wallet / credit_card or merchand operationId: listTransactions description: " 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. " produces: - application/json parameters: - in: query name: creditcard_id description: pass an optionnal creditcrad_id for looking up inventory required: false type: string - in: query name: page description: request page number type: integer format: int32 minimum: 1 - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 10 maximum: 100 - in : query name : status description : 'filter the result by transaction status' type : enum example: 'CONFIRMED' values : ['NEW','AUTHORIZED','AUTHORIZED_WAITING_3DS','CONFIRMED','CANCELLED','REFUNDED'] - in : query name : type description : Filer the result by transaction type. type : enum example: 'ALL' values : ['ALL','PAYMENT','REFUND'] - in: query name: wallet_id description: pass an optional wallet_id for looking up inventory required: false type: string responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Transaction' 400: description: bad input parameter /charges/: get: tags: - Charge summary: List charges for a merchant operationId: listCharges description: " 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. " produces: - application/json parameters: - in: query name: page description: request page number type: integer format: int32 minimum: 1 - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 10 maximum: 100 - in: query name: status type: string enum: ['NEW','PENDING','AUTHORIZED','CONFIRMED','CANCELLED','FAILED','SUSPENDED'] example: 'PENDING' description: Status of the billing charge responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Charge' 400: description: bad input parameter /charges/$id: get: tags: - Charge summary: Get charge details. operationId: chargeDetails description: " Return details of the charge for the given id. The transaction related are return as nested objects." consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass charge id required: true type: string responses: 200: description: Charge Detail schema: type: object $ref: '#/definitions/Charge' 400: description: bad input parameter put : tags: - Charge summary: Update charge details. operationId: updateCharge description: " 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." consumes: - application/json produces: - application/json parameters: - in: body name: updateChargeRequest description: Pass the propertiers for charge update schema: $ref: '#/definitions/updateChargeRequest' responses: 200: description: Charge Detail schema: type: object $ref: '#/definitions/Charge' 400: description: bad input parameter delete: tags: - Charge summary: Cancel the charge. operationId: cancelCharge description: "Cancel the future charge. The payment will not be done. The related subscription is not closed." consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass charge id required: true type: string responses: 200: description: Charge Detail schema: type: object $ref: '#/definitions/Charge' 400: description: bad input parameter /plans: post: tags: - Plan summary: Create a plan for recurring charge operationId: createPlan description : " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: createPlanRequest description: Pass the propertiers for plan creation schema: $ref: '#/definitions/createPlanRequest' responses: 200 : description: Plan detail schema: type: object $ref: "#/definitions/Plan" 400: description: bad input parameter get: tags: - Plan summary: List plans for a merchand operationId: listPlans description: "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." produces: - application/json parameters: - in: query name: page description: request page number type: integer format: int32 minimum: 1 - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 10 maximum: 100 responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Plan' 400: description: bad input parameter /plans/$id: get: tags: - Plan summary: Get plan details. operationId: planDetails description: "Get plan details for the given identifier." consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass plan id required: true type: string responses: 200: description: Plan Detail schema: type: object $ref: '#/definitions/Plan' 400: description: bad input parameter delete: tags: - Plan summary: Delete the plan if not used. operationId: deletePlan description: " 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. " consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass plan id required: true type: string responses: 200: description: Plan Detail schema: type: object $ref: '#/definitions/Plan' 400: description: bad input parameter put: tags: - Plan summary: Update a plan operationId: updatePlan description : " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: updatePlanRequest description: Pass the propertiers for plan update schema: $ref: '#/definitions/updatePlanRequest' responses: 200 : description: Plan details schema: type: object $ref: "#/definitions/Plan" 400: description: bad input parameter /products: post: tags: - Product summary: Create a product operationId: createProduct description : " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: createProductRequest description: Pass the propertiers for product creation schema: $ref: '#/definitions/createProductRequest' responses: 200 : description: Product details schema: type: object $ref: "#/definitions/Product" 400: description: bad input parameter get: tags: - Product summary: List products for a merchand operationId: listProducts description: " List all products for this partners. " produces: - application/json parameters: - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 10 maximum: 100 - in: query name: page description: request page number type: integer format: int32 minimum: 1 responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Product' 400: description: bad input parameter /products/$id: get: tags: - Product summary: Get product details. operationId: productDetails description: "Get product details for the given identifier." consumes: - application/json produces: - application/json parameters: - in: query name: id description: The product id required: true type: string responses: 200: description: Product Detail schema: type: object $ref: '#/definitions/Product' 400: description: bad input parameter delete: tags: - Product summary: Desactivate a product for futher subscription. operationId: desactivateProduct description: " Disactivate the product with the given id, the product would not be available for subscription anymore. A DISACTIVED product cannot be reactivated." consumes: - application/json produces: - application/json parameters: - in: query name: id description: the product id example 'hbo_access_eur_d290f1ee' required: true type: string responses: 200: description: Product Details schema: type: object $ref: '#/definitions/Product' 400: description: bad input parameter put: tags: - Product summary: Update a product operationId: updateProduct description : " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: updateProductRequest description: Pass the propertiers for product update schema: $ref: '#/definitions/updateProductRequest' responses: 200 : description: Product details schema: type: object $ref: "#/definitions/Product" 400: description: bad input parameter /subscriptions/init: post: tags: - Core functionnality summary: Create a web subscription operationId: webSubscription description: " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: webSubscription description: Pass the propertiers for subscription creation schema: $ref: '#/definitions/webSubscriptionRequest' responses: 200: description: Parameters used for redirection or javascript integration schema: $ref: '#/definitions/webResponse' 400: description: bad input parameter /subscriptions/$id: get: tags: - Subscription summary: Get subscription details. operationId: subscriptionDetails description: " Return the subscription details." consumes: - application/json produces: - application/json parameters: - in: query name: id description: The subscription id required: true type: string responses: 200: description: Subscription Detail schema: type: object $ref: '#/definitions/Subscription' 400: description: bad input parameter delete: tags: - Subscription summary: Close subscription. operationId: desactivateSubscription description: "Desactivate the subscription, no later payment will be send. The pending charge are also cancel. The is no way to reactivate a closed subscription." consumes: - application/json produces: - application/json parameters: - in: query name: id description: "the subscription id " required: true type: string responses: 200: description: Subscription Detail schema: type: object $ref: '#/definitions/Subscription' 400: description: bad input parameter /subscriptions: post: tags: - Subscription summary: Create a subscription operationId: createSubscription description : " 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. " consumes: - application/json produces: - application/json parameters: - in: body name: createSubscriptionRequest description: Pass the propertiers for subscription creation schema: $ref: '#/definitions/createSubscriptionRequest' responses: 200 : description: Product details schema: type: object $ref: "#/definitions/Subscription" 400: description: bad input parameter get: tags: - Subscription summary: List subscription for a wallet / credit card / product / plan / status for a merchand operationId: listSubscriptions description: "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. " produces: - application/json parameters: - in: query name: creditcard_id description: "pass an optional creditcard identifier for looking up inventory, the related wallet identifier must be given " required: false type: string - in: query name: page description: request page number type: integer format: int32 minimum: 1 - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 0 maximum: 100 - in: query name: plan_id description: pass an optional plan identifier for looking up inventory required: false type: string - in: query name: product_id description: "pass an optional product identifier for looking up inventory" required: false type: string - in: query name : status description: "Filter the search by subscription status" type : enum values : ['ACTIVE','INACTIVE'] - in: query name: wallet_id description: "pass an optional wallet identifier for looking up inventory" required: false type: string responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Subscription' 400: description: bad input parameter /subscriptions/$subscriptionId/charges: get: tags: - Charge summary: List charges for a subscription operationId: listSubscriptionCharges description: " 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. " produces: - application/json parameters: - in: query name: page description: request page number type: integer format: int32 minimum: 1 - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 10 maximum: 100 - in: query name: subscriptionId description: pass subscription id for listing charge type: string - in: query name: status type: string enum: ['NEW','PENDING','AUTHORIZED','CONFIRMED','CANCELLED','FAILED','SUSPENDED'] example: 'PENDING' description: Status of the billing charge responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Charge' 400: description: bad input parameter /wallets: post: tags: - Wallet summary: Create a wallet operationId : createWallet description : "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." consumes: - application/json produces: - application/json responses: 200: description: Wallet Detail schema: type: object $ref: '#/definitions/walletCreationResponse' 400: description: bad input parameter get: tags: - Wallet summary: Get the wallet list. operationId: walletList description: "Get the wallet list filtered by status." consumes: - application/json produces: - application/json parameters: - in: query name: page description: request page number type: integer format: int32 minimum: 1 - in: query name: per_page description: number of records per page type: integer format: int32 minimum: 0 maximum: 100 - in: query name : status description: "Filter the search by wallet status" type : enum values : ['OPEN','DISACTIVATED'] responses: 200: description: search results matching criteria schema: type: array items: $ref: '#/definitions/Wallet' 400: description: bad input parameter /wallets/$id: get: tags: - Wallet summary: Get wallet details. operationId: walletDetails description: "Get the wallet details with status and registered cards." consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass wallet id required: true type: string responses: 200: description: Wallet Detail schema: type: object $ref: '#/definitions/Wallet' 400: description: bad input parameter delete: tags: - Wallet summary: Desactivate the wallet. operationId: desactivateWallet description: "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." consumes: - application/json produces: - application/json parameters: - in: query name: id description: pass wallet id required: true type: string responses: 200: description: Wallet Detail schema: type: object $ref: '#/definitions/Wallet' 400: description: bad input parameter definitions: Charge: type: object required: - id - amount - date_created - subscription_id - status properties: date_created: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2018-10-01T09:12:33.001Z' description: Date of creation of charge id: type: string format: uuid example: illimited_monthly_billing-90e6-111 description: The unique charge identifier use in requests amount: type: number minimum: 0.01 example: 12.00 description: The amount of the charge currency: type: string enum: ['EUR','PLN','GBP','DKK','SEK','NOK','CHF','RON'] example: 'EUR' description : 'The currency for this charge' payment_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2018-10-01T09:12:33.001Z' description: The date when the payment has succeed. Only feeled if payment has succeed. send_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2018-10-01T09:12:33.001Z' description: the date when the payment will be done. status: type: string enum: ['NEW','PENDING','AUTHORIZED','CONFIRMED','CANCELLED','FAILED','SUSPENDED'] example: 'PENDING' description: Status of the billing charge subscription_id: type: string example: s-1212_13313_131331 description: The subscription id related to this charge transactions: type: array items: $ref: '#/definitions/Transaction' Creditcard: type: object required: - id - creation_date - status - brand - expiry_date properties: brand : type: string enum: ['VISA','MASTERCARD','CB'] example: 'VISA' description: credit card status creation_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2016-08-29T09:12:33.001Z' expiry_date: type: string description : 'Credit card expiration date' format: 'MM/YYYY' example: '01/2019' id: type: string format: uuid example: 'd290f1ee-6c54-4b01-90e6-d701748f0851' pan: type : string example: '4000 XXXX XXXX XXXX' description: Offusced Pan status : type: string enum: ['VALIDATED','EXPIRED','SUSPENDED','BLOCKED'] example: 'VALIDATED' description: credit card status Plan: type: object required: - external_id - charge_count properties: id: type: string format: uuid example: illimited_monthly_billing-90e6-111 description : Unique identifier used to take subscription charge_count: type: number minimum: -1 example : -1 description: The number charges that will be established. -1 stand for illimited charges. external_id: type: string example: illimited_monthly_billing description: Merchant significant identifier interval: type: string enum: ['DAY','WEEK','MONTH'] example: 'MONTH' description: Define the billing period unit interval_count: type: number minimum: 1 maximum: 52 example: 1 description: The number of interval between two billing name: type: string example: Illimited monthly billing description : Merchant convenience name status: type: string enum: ['ACTIVE','INACTIVE','DISACTIVATED'] example: 'ACTIVE' description: Status of the plan Product: type: object required: - amount - currency - external_id - status properties: id: type: string format: uuid example: hbo_access_eur_d290f1ee description: Unique product identifier use to make subscription amount: type: number minimum: 0.01 example: 12.00 description: The amount of the product currency: type: string enum: ['EUR','PLN','GBP','DKK','SEK','NOK','CHF','RON'] example: 'EUR' description : The device of billing external_id: type: string example: HBO_ACCESS_EUR description: Merchant convenience identifier name: type: string example: HBO ACCESS description : Merchant convenience name status: type: string enum: ['ACTIVE','INACTIVE','DISACTIVATED'] example: 'ACTIVE' description: Status of the product Subscription: type: object required: - wallet_id - creditcard_id - product_id - plan_id - external_id properties: cancel_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2019-10-01T09:12:33.001Z' description: Date of cancellation creditcard_id: type: string format: uuid example: 'WC-123343444' description: The identifier of the creditcard used to subscribe end_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2019-10-01T09:12:33.001Z' description: The planned endDate for limited recurring plan. Void if unlimited external_id: type: string format: uuid example: 'M_TRX_0000001' description: Option externalID given by the merchant. Not used by the system. id: type: string format: uuid example: 'illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851' description: The unique subscription identifier generate by service product_id: type: string format: uuid example: hbo_access_eur_d290f1ee description: The product identifier recurrely billed plan_id: type: string format: uuid example: illimited_monthly_billing-90e6-111 description: The plan identifier whitch describes the billing frequency status: type: string enum: ['NEW','ACTIVE','TERMINATION_PENDING','TERMINATED','CANCELLED'] example: ACTIVE subscription_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2018-10-01T09:12:33.001Z' description: Subscription date wallet_id: type: string format: uuid example: 'WA-d701748f0851' description: The identifier of wallet involve for the subscription Transaction: type: object required: - id - status - amount - creation_date - authorization_date - authorization_timeout_date - wallet_id - creditcard properties: amount: type: number minimum: 0.01 example: 10.00 authorization_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2016-08-29T09:12:33.001Z' authorization_timeout_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2016-08-29T09:12:33.001Z' creation_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2016-08-29T09:12:33.001Z' creditcard: type: object $ref: '#/definitions/Creditcard' currency: type: string enum: ['EUR','PLN','GBP','DKK','SEK','NOK','CHF','RON'] example: 'EUR' external_id: type: string format: uuid example: 'M_TRX_0000001' description: Option externalID given by the merchant. Not used by the system. id: type: string format: uuid example: 'd290f1ee-6c54-4b01-90e6-d701748f0851' status: type: string enum: ['NEW','CANCELLED','FAILED','CONFIRMED','AUTHORIZED','EXPIRED'] example: 'CONFIRMED' subscription_id: type: string format: uuid example: 'illimited_monthly_billing_hbo_access_eur_d290f1ee_d701748f0851' type: type: object enum: ['PAYMENT','REFUND'] example: 'PAYMENT' wallet_id: type: string format: uuid example: 'WA-d701748f0851' Wallet : type: object required: - id - status - creation_date - creditcards properties: id: type: string format: uuid example: d290f1ee-6c54-4b01-90e6-d701748f0851 description : The unique identifier used to reference this wallet during payment creation_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2016-08-29T09:12:33.001Z' description: Wallet creation date creditcards: type: array items: $ref: '#/definitions/Creditcard' description : list of creditcard attached at this wallet status : type: string enum: ['OPEN','DISACTIVATED',] example: 'OPEN' description: The wallet status confirmRequest: type: object required: - amount properties: amount: type: number minimum: 0.01 example: 12.00 createPlanRequest: type: object required: - external_id - charge_count - interval properties: charge_count: type: number minimum: -1 example : -1 description : The max number of charge to proceed. -1 is used to refer a illimited renewal. Values below -1 and 0 are forbidden. external_id: type: string example: illimited_monthly_billing description : merchant significant identifier interval: type: string enum: ['DAY','WEEK','MONTH'] example: 'MONTH' description: Define the billing interval unit interval_count: type: number minimum: 1 maximum: 52 example: 1 default : 1 description: The number of interval between two blling name: type: string example: Illimited monthly billing description : Merchant convenience name status: type: string enum: ['ACTIVE','INACTIVE'] example: 'ACTIVE' description: Status of the plan createProductRequest: type: object required: - amount - external_id properties: amount: type: number minimum: 0.01 example: 12.00 description: The amount of the product currency: type: string enum: ['EUR','PLN','GBP','DKK','SEK','NOK','CHF','RON'] example: 'EUR' description : The device of billing external_id: type: string example: HBO_ACCESS_EUR description: Merchant convenience identifier name: type: string example: HBO ACCESS description : Merchant convenience name status: type: string enum: ['ACTIVE','INACTIVE'] example: 'ACTIVE' description: Status of the product createSubscriptionRequest: type: object required: - wallet_id - creditcard_id - product_id - plan_id - external_id properties: creditcard_id: type: string format: uuid example: 'WC-123343444' description: The identifier of the creditcard used to subscribe external_id: type: string format: uuid example: 'M_TRX_0000001' description: Option externalID given by the merchant. Not used by the system. plan_id: type: string format: uuid example: illimited_monthly_billing-90e6-111 description: The plan identifier whitch describes the billing frequency product_id: type: string format: uuid example: hbo_access_eur_d290f1ee description: The product identifier that will be recurrely billed wallet_id: type: string format: uuid example: 'WA-d701748f0851' description: The identifier of wallet involve for the subscription updateChargeRequest: type: object required: - status properties: amount: type: number minimum: 0.01 example: 12.00 description: The amount of the charge status: type: string enum: ['PENDING','CANCELLED','SUSPENDED'] example: 'PENDING' description: Status of the billing charge updatePlanRequest: type: object properties: external_id: type: string example: illimited_monthly_billing description : merchant significant identifier name: type: string example: Illimited monthly billing description : Merchant convenience name status: type: string enum: ['ACTIVE','INACTIVE'] example: 'ACTIVE' description: Status of the plan updateProductRequest: type: object properties: external_id: type: string example: HBO_ACCESS_EUR description: Merchant convenience identifier name: type: string example: HBO ACCESS description : Merchant convenience name status: type: string enum: ['ACTIVE','INACTIVE'] example: 'ACTIVE' description: Status of the product refundRequest: type: object required: - amount properties: amount: type: number minimum: 0.01 example: 12.00 external_id: type: string format: uuid example: R-D12131321 walletAuthorizeRequest: type: object required: - amount - wallet_id - creditcard_id - external_id properties: amount: type: number minimum: 0.01 example: 12.00 description : 'The amount of payment' creditcard_id: type: string format: uuid example: 'WC-123343444' description : 'The credit card on whitch the payment will be done.' currency: type: string enum: ['EUR','PLN','GBP','DKK','SEK','NOK','CHF','RON'] example: 'EUR' description : 'The currency for this authorize, if not given the default merchant currency is used' external_id: type: string format: uuid example: 'M_TRX_0000001' description: Option externalID given by the merchant. Not used by the system. wallet_id: type: string format: uuid example: 'WA-d701748f0851' description: 'The wallet to use for payment' walletCreationResponse : type: object required: - id - status - creation_date properties: id: type: string format: uuid example: d290f1ee-6c54-4b01-90e6-d701748f0851 description : The unique identifier used to reference this wallet during payment creation_date: type: string format: "yyyy-MM-dd'T'HH:mm:ss'Z'" example: '2016-08-29T09:12:33.001Z' description: Wallet creation date status : type: string enum: ['OPEN','DISACTIVATED',] example: 'OPEN' description: The wallet status webAuthorizeRequest: type: object required: - amount - description - external_id - return_url properties: # 3DS : # type: string # enum: ['none','mandatory','managed'] # description: ' Choose if the payment have to be done using 3DS security workflow. none -> No 3DS , mandatory -> 3DS is mandatory , # managed -> 3DS mandatory if available for card. Usage of this parameter is restricted to selected merchant.' # example: 'none' # default: 'mandatory' amount: type: number minimum: 0.01 example: 12.00 description: 'Amount of the payment' auto_confirm: type: boolean example : false description : 'Specify if the payment will be done in two steps (authorize/confirm) with merchant interaction, by defaut the confirmation is done asynchronously automatically.' default: true creditcard_id: type: string format: uuid example: 'WC-123343444' description : '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: type: string enum: ['EUR','PLN','GBP','DKK','SEK','NOK','CHF','RON'] example: 'EUR' description : 'The currency for this authorize, if not given the default merchant currency is used' display_creditcard_list: type: boolean description: Choose to display the already registered and valid credit card example: true default : 'false' external_id: type: string format: uuid example: P-D12131321 description : 'The merchant payment reference, unicity will not be checked.' language : type : string enum: ['da','de','en','es','fi','fr','it','nl','no','pl','pt','ro','sk','sv'] example: 'fr' description: '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 ' default : 'Browser language detection or english if language not available' mandatory_wallet_cvx: type: boolean example: true description: Choose to ask creditcard cvx for wallet interractive payment. default : 'true' template : type: string enum: ['skeleton','bootstrap4','boosted'] example: 'bootstrap4' description: 'The css framework to use to display, by default the bootstrap template will be used.' default : 'bootstrap4' return_url: type : string description: 'The return url used at the end of purchase workflow to notify the merchant if payment succeed or not. ' example : 'https://achile-service.com/payment-return' skip_user_validation: type: boolean example: false description: "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. " default : 'false' wallet_id: type: string format: uuid example: 'WA-d701748f0851' description : '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: type: string enum: ['no','implicit','suggest','suggest_mandatory'] description: Choose to suggest card memorize to user, the card will be register on the given wallet_id example: 'suggest' default: 'no' webSubscriptionRequest: type: object required: - external_id - product_id - plan_id - return_url - wallet_id properties: # 3DS : # type: string # enum: ['none','mandatory','managed'] # description: ' Choose if the payment have to be done using 3DS security workflow. none -> No 3DS , mandatory -> 3DS is mandatory , # managed -> 3DS mandatory if available for card. Usage of this parameter is restricted to selected merchant.' # example: 'none' # default: 'mandatory' # amount: # type: number # minimum: 0.01 # example: 12.00 # description: 'Optionnal amount which will replace the product price for this subscription' # auto_confirm: # type: boolean # example : false # description : 'Specify if the payment will be done in two steps (authorize/confirm) with merchant interaction, by defaut the confirmation is done asynchronously automatically.' # default: true creditcard_id: type: string format: uuid example: 'WC-123343444' description : '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: type: boolean description: Choose to display the already registered and valid credit card example: true default : 'false' display_accept_subscription: type : boolean example : true description : '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.' default : 'true' external_id: type: string format: uuid example: P-D12131321 description : 'The merchant payment reference, unicity will not be checked.' language : type : string enum: ['da','de','en','es','fi','fr','it','nl','no','pl','pt','ro','sk','sv'] example: 'fr' description: '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 ' default : 'Browser language detection or english if language not available' mandatory_wallet_cvx: type: boolean example: true description: Choose to ask creditcard cvx for wallet interractive payment. default : 'true' plan_id: type : string format: uuid example : 'P-31FAD3-AEADA89-88377A' description : 'The recurring plan used to charge the subscription.' product_id: type : string format: uuid example : 'P-c123dda-adcb5-de876' description: 'The product to bill and subscribe with the given billing plan. Only used for recurring subscription.' template : type: string enum: ['skeleton','bootstrap4','boosted'] example: 'bootstrap4' description: 'The css framework to use to display, by default the bootstrap template will be used.' default : 'bootstrap4' return_url: type : string description: 'The return url used at the end of purchase workflow to notify the merchant if payment succeed or not. ' example : 'https://achile-service.com/payment-return' skip_user_validation: type: boolean example: false description: "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. " default : 'false' wallet_id: type: string format: uuid example: 'WA-d701748f0851' description : '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. ' webResponse: type: object required: - token - url properties: payment_token: type: string example: 'AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4' description : "A token to provide to the payment service to include the payment panel (see Credit Card Payment Panel)" payment_url: type: string example: 'https://secure-cb.w-ha.com/contodeo/purchaseForm' description: 'The URL of the payment service to include the payment panel (see Credit Card Payment Panel)' redirect_url: type: string example: 'https://secure-cb.w-ha.com/contodeo/purchaseForm?token=AEZAOKFDKOKOKXOKDQPKFPQKFPDKFPDKFK1243K4K4' description: 'URL of the payment panel where the partner should redirect the user to perform payment authorization.' # Added by API Auto Mocking Plugin host: contodeo.w-ha.com basePath: /contodeo/api schemes: - https