Confirmations

Authentication

To use the Confirmation APIs you will need an API Token, which can be requested to support or navigating on your account to Users > Details > Api Token.

With that token, you’ll be able to access our API. You should send your key in every request to our API, in order to authenticate and identify yourself. For every request, you should pass the Authorization HTTP Header containing your token, prefixed by “Bearer “ string. Example below:

curl -H 'PAYCERTIFYKEY: YOUR_API_KEY' https://confirmation-api.paycertify.com/api/confirmations

An authentication error message would return a message like the following:

{
    "error": {
        "status": 401,
        "message": {
            "base": [
                "Not authenticated"
            ]
        }
    }
}

Please note that the error messages use the same structure of an error node, with then a message node, and subsequently either base being a general error, unrelated to any field submitted, fatal being a system error, or a field name, for example, amount when the request message contains any errors under that field. All messages also contain an HTTP status following W3C recommendations, e.g. an unauthenticated request will return HTTP status 401.

We include the HTTP status on the JSON message, as well as on the headers of all JSON error responses.

Overview

PayCertify provides you different ways to get confirmed about the authenticity of your customer’s information. Currently we offer six different strategies that are detailed below. The procedure used to trigger a confirmation process is the same for all strategies.

Before starting to use one of the confirmation strategies available, you must create an initial template for it. This will provide you an initial set of default messages that will be used in the interaction with the end-users that will receive confirmation messages. These messages will appear in the email and sms bodies, web interfaces and into all communication steps. The template creation process is described here.

Each template contain a set of messages that will be displayed to your customer in a given moment of the confirmation process. When a confirmation template is created, these messages are scaffolded with default contents, and they can be modified/customized by using this same API in order to achieve the desired look-and-feel and branding. Also, by customizing these messages you’re allowed to add any particular information that you expect to be shown to your customer into the messages.

It worths to say that once a template is created and customized for a given confirmation strategy, it can be used to trigger many confirmation processes. Of course you can have more than one template for each confirmation strategy, and this will make total sense when a merchant have more than one portal or ecommerce store.

For each confirmation strategy we’ll show you how to create a template and how to use it to dispatch a confirmation for your customer. Below we will show you the six strategies currently implemented in our API: email_ecommerce, email_moto, phone_ecommerce and phone_moto, email_moto_secure, phone_moto_secure.

For each action taken in a confirmation process, the API composes a complete log that provides you a detailed view of the customer’s behavior in this process. Also, whenever the customer interacts with the process, navigation-specific data (IP location, browser details) is gathered and stored with the related actions.

Moreover, you can provide a callback URL in order to receive updates of confirmation process statuses in your own system. This allow you to have a full-automated process integrated with your system’s workflow.

Email-Ecommerce

This strategy is used whenever you want to have a simple confirmation of the consumer email’s authenticity. An email will be dispatched for your customer with a confirmation link. Once the customer receives it and clicks in the link, the process will be finished.

To trigger a new confirmation process, you must make an authenticated request by using the following URL.

POST https://confirmation-api.paycertify.com/api/confirmations

Parameter Type Presence Description Example
confirmation_template_id uuid Required A template ID that relates to this confirmation strategy. You must use a confirmation template created for email_ecommerce process type. 63693de5-8a19-4233-b382-c75f0c6b31aa
email_address string Required The user’s email that you want to get confirmed example@domain.com
timeout_seconds string Optional Timeout in seconds (default 300 seconds) 600
callback_url string Optional The callback URL http://hooks.my.com/paycertify
Field Type Description Example
id uuid The confirmation ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. The possible states are: idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process_name string The selected process strategy name email_ecommerce
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. The states available are idle, generating_token, sending_email, waiting_response, finished, failed waiting_response
process.email_address string Email example@domain.com
process.timeout_seconds string Time in seconds 300
process.fail_reason string A fail description when process fails Delivery Error
process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Action ID ce388e8a-300a-4833-b716-48f85251b839
confirmation_actions.*.created_at datetime Action created at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Action name start
confirmation_actions.*.actor string Action’s actor merchant
confirmation_actions.*.executed string If action is executed or not true
confirmation_actions.*.error_message string Error message Delivery Error
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'confirmation_template_id=15be8861-597a-4b7b-a0aa-b7486ba3de7e' \
  --form 'timeout_seconds=300' \
  --form 'email_address=example@domain.com'

Responds with:

{
    "id": "ca8d77c9-4477-4f48-bbea-9bc52264e74d",
    "created_at": "2018-07-05T14:09:40.098Z",
    "updated_at": "2018-07-05T14:09:40.110Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "email_ecommerce",
    "process": {
        "id": "df3a192a-33d2-4d98-8e2d-29709c73e840",
        "state": "waiting_response",
        "email_address": "example@domain.com",
        "timeout_seconds": 60,
        "fail_reason": null,
        "created_at": "2018-07-05T14:09:40.092Z",
        "updated_at": "2018-07-05T14:09:40.137Z"
    },
    "confirmation_actions": [
        {
            "id": "d198c09a-6713-4fa3-ba75-187a409bf2b5",
            "created_at": "2018-07-05T14:09:40.106Z",
            "action_name": "start",
            "actor": "merchant",
            "parameters": {
                "email_address": "example@domain.com",
                "timeout_seconds": "60"
            },
            "executed": null,
            "error_message": null
        }
    ]
}

Email-MOTO

This strategy is designed to be used in a MOTO (mail order/telephone order) environment. It works similarly to the Email-Ecommerce strategy and the parameters provided and received are the same. However, this process requires the consumer to perform one step more; after clicking in the email message’s link, the user will be directed to an intermediary screen where it must agree with a disclaimer in order to accomplish the confirmation process. This disclaimer shall be configured directly in your agreement message available at your confirmation template.

To trigger an Email-Moto confirmation process, you must make an authenticated request by using the following URL.

POST https://confirmation-api.paycertify.com/api/confirmations

Parameter Type Presence Description Example
confirmation_template_id uuid Required A template ID that relates to this confirmation strategy. 63693de5-8a19-4233-b382-c75f0c6b31aa
email_address string Required The user’s email that you want to confirm example@domain.com
timeout_seconds string Optional Timeout in seconds (default 60 seconds) 90
callback_url string Optional The callback URL http://hooks.my.com/paycertify
Field Type Description Example
id uuid The confirmation ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. States available are idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process_name string The selected process strategy name email_moto
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. States available are: idle, generating_token, sending_email, waiting_click, waiting_agreement, finished, failed waiting_click
process.email_address string Email example@domain.com
process.timeout_seconds string Time in seconds 60
process.fail_reason string A fail description when process fails Delivery Error
process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Action ID ce388e8a-300a-4833-b716-48f85251b839
confirmation_actions.*.created_at datetime Action created at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Action name start
confirmation_actions.*.actor string Action’s actor merchant
confirmation_actions.*.executed string If action is executed or not true
confirmation_actions.*.error_message string Error message Delivery Error
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'confirmation_template_id=15be8861-597a-4b7b-a0aa-b7486ba3de7e' \
  --form 'timeout_seconds=600' \
  --form 'email_address=example@domain.com'

Responds with:

{
    "id": "ca8d77c9-4477-4f48-bbea-9bc52264e74d",
    "created_at": "2018-07-05T14:09:40.098Z",
    "updated_at": "2018-07-05T14:09:40.110Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "email_moto",
    "process": {
        "id": "df3a192a-33d2-4d98-8e2d-29709c73e840",
        "state": "waiting_click",
        "email_address": "example@domain.com",
        "timeout_seconds": 600,
        "fail_reason": null,
        "user_response": null,
        "created_at": "2018-07-05T14:09:40.092Z",
        "updated_at": "2018-07-05T14:09:40.137Z"
    },
    "confirmation_actions": [
        {
            "id": "d198c09a-6713-4fa3-ba75-187a409bf2b5",
            "created_at": "2018-07-05T14:09:40.106Z",
            "action_name": "start",
            "actor": "merchant",
            "executed": null,
            "error_message": null
        }
    ]
}

Phone-Ecommerce

This confirmation strategy is similar to Email-Ecommerce strategy. However, it targets to confirm the consumer’s phone number through an sms message instead of an email message. SMS message templates shall be interpreted as plain-text messages, which means that HTML tags won’t be rendered correctly. URLs in the SMS body are usually transformed into clickable links by the mobile device itself.

It worths to say that all the links received in the SMS-based processes are shortened with our safe and proprietary url-shortener service (links are rendered as https://pcer.co/{UNIQUE_TOKEN}).

To trigger a new confirmation process, you must make an authenticated request by using the following URL:

POST https://confirmation-api.paycertify.com/api/confirmations

Parameter Type Presence Description Example
confirmation_template_id uuid Required A template ID that relates to this confirmation strategy. 63693de5-8a19-4233-b382-c75f0c6b31aa
phone_number string Required The user’s phone number that you want to confirm (in E.164 format) +11231231234
timeout_seconds string Optional Timeout in seconds (default 60 seconds) 90
callback_url string Optional The callback URL http://hooks.my.com/paycertify
Field Type Description Example
id uuid The template ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. States available are: idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process_name string The selected process strategy name phone_ecommerce
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. The states available are idle, generating_token, sending_sms, waiting_token, finished, failed sending_sms
phone_number string The user’s phone number that you want to confirm (in E.164 format) +11231231234
process.timeout_seconds string Time in seconds 60
process.fail_reason string Status of this template  
process.merchant_id uuid The UUID of merchant 48a872f9-9389-4047-be85-a38d291e62b3
process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Status of this template  
confirmation_actions.*.created_at datetime Status of this template 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Status of this template  
confirmation_actions.*.actor string Status of this template  
confirmation_actions.*.executed string Status of this template  
confirmation_actions.*.error_message string Status of this template  
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'confirmation_template_id=a37e67e4-af37-4ebf-af48-80ffade48c4b' \
  --form 'phone_number=+5531992274225' \
  --form 'timeout_seconds=540'

Responds with:

{
    "id": "3c86e137-1e59-4af5-bf9d-8f6b2970d4f9",
    "created_at": "2018-07-05T14:55:36.171Z",
    "updated_at": "2018-07-05T14:55:36.183Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "phone_ecommerce",
    "process": {
        "id": "e8ef69e8-c50d-41ce-b306-a281217cb024",
        "state": "waiting_token",
        "phone_number": "+5531992274225",
        "timeout_seconds": 540,
        "fail_reason": null,
        "merchant_id": "48a872f9-9389-4047-be85-a38d291e62b3",
        "created_at": "2018-07-05T14:55:36.165Z",
        "updated_at": "2018-07-05T14:55:39.947Z"
    },
    "confirmation_actions": [
        {
            "id": "152283ba-3959-4871-8f87-2a246995c17f",
            "created_at": "2018-07-05T14:55:36.179Z",
            "action_name": "start",
            "actor": "merchant",
            "parameters": {
                "phone_number": "+5531992274225",
                "timeout_seconds": "540"
            },
            "executed": null,
            "error_message": null
        }
    ]
}

Phone-Moto

This confirmation strategy is similar to Email-Moto strategy, but it targets to confirm the consumer’s phone number through an sms message inside of a MOTO (mail order/telephone order) environment. There will be an intermediary step where the consumer must agree with a disclaimer before finishing the confirmation process. SMS message templates shall be interpreted as plain-text messages, so HTML tags won’t be rendered correctly. URLs in the SMS body are usually transformed in clickable links by the mobile device itself.

It worths to say that all the links received in the SMS-based processes are shortened with our safe and proprietary url-shortener service (links are rendered as https://pcer.co/{UNIQUE_TOKEN}).

To trigger a new confirmation process, you must make an authenticated request by using the following URL.

POST https://confirmation-api.paycertify.com/api/confirmations

Parameter Type Description Example
confirmation_template_id uuid The template ID 63693de5-8a19-4233-b382-c75f0c6b31aa
phone_number string Status of this template example@domain.com
timeout_seconds string Time 90
callback_url string Url 90
Field Type Description Example
id uuid The template ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. States available are: idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. The states available are idle, generating_token, sending_sms, waiting_token, waiting_agreement, finished, failed sending_sms
phone_number string The user’s phone number that you want to confirm (in E.164 format) +11231231234
process.timeout_seconds string Time in seconds 60
process.fail_reason string Status of this template  
process.created_at datetime Status of this template 2018-07-05T14:09:40.106Z
process.updated_at datetime Status of this template 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Status of this template  
confirmation_actions.*.created_at datetime Status of this template 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Status of this template  
confirmation_actions.*.actor string Status of this template  
confirmation_actions.*.executed string Status of this template  
confirmation_actions.*.error_message string Status of this template  
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'confirmation_template_id=54dadf8b-b4f3-4b47-87e9-a4a1b48e59bd' \
  --form 'phone_number=+11231231234' \
  --form 'timeout_seconds=540'

Responds with:

{
    "id": "29fce109-0fdd-4c54-a1c0-62d02d799d94",
    "created_at": "2018-07-05T15:09:21.391Z",
    "updated_at": "2018-07-05T15:09:21.400Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "phone_moto",
    "process": {
        "id": "94cc2188-16f2-4f85-883f-44902a26262f",
        "state": "waiting_token",
        "phone_number": "+11231231234",
        "timeout_seconds": 540,
        "fail_reason": null,
        "merchant_id": "48a872f9-9389-4047-be85-a38d291e62b3",
        "created_at": "2018-07-05T15:09:21.386Z",
        "updated_at": "2018-07-05T15:09:23.905Z"
    },
    "confirmation_actions": [
        {
            "id": "75f8985b-4f70-4c20-baba-9fcc07fcc481",
            "created_at": "2018-07-05T15:09:21.397Z",
            "action_name": "start",
            "actor": "merchant",
            "executed": null,
            "error_message": null
        }
    ]
}

Email-MOTO-Secure

This strategy works similarly to the Email-MOTO strategy but includes 3D-Secure verification in its pipeline. This process requires the consumer to confirm credit card and order details and agree with the disclaimer before proceeding. After submitting its agreement and confirm the transaction, the API response will additionally receive the results for the 3D-Secure process with verdict.

To trigger an Email-MOTO-Secure confirmation process, you must make an authenticated request by using the following URL.

POST https://confirmation-api.paycertify.com/api/confirmations

Parameter Type Presence Description Example
confirmation_template_id uuid Required A template ID that relates to this confirmation strategy. 63693de5-8a19-4233-b382-c75f0c6b31aa
email_address string Required The user’s email that you want to confirm example@domain.com
timeout_seconds string Optional Timeout in seconds (default 60 seconds) 90
callback_url string Optional The callback URL http://hooks.my.com/paycertify
Field Type Description Example
id uuid The confirmation ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. States available are idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process_name string The selected process strategy name email_moto_secure
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. States available are: idle, generating_token, sending_email, waiting_click, waiting_agreement, finished, failed waiting_click
process.email_address string Email example@domain.com
process.timeout_seconds string Time in seconds 60
process.fail_reason string A fail description when process fails Delivery Error
process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Action ID ce388e8a-300a-4833-b716-48f85251b839
confirmation_actions.*.created_at datetime Action created at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Action name start
confirmation_actions.*.actor string Action’s actor merchant
confirmation_actions.*.executed string If action is executed or not true
confirmation_actions.*.error_message string Error message Delivery Error
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'confirmation_template_id=15be8861-597a-4b7b-a0aa-b7486ba3de7e' \
  --form 'timeout_seconds=600' \
  --form 'email_address=example@domain.com'

Responds with:

{
    "id": "ca8d77c9-4477-4f48-bbea-9bc52264e74d",
    "created_at": "2018-07-05T14:09:40.098Z",
    "updated_at": "2018-07-05T14:09:40.110Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "email_moto_secure",
    "process": {
        "id": "df3a192a-33d2-4d98-8e2d-29709c73e840",
        "state": "waiting_click",
        "email_address": "example@domain.com",
        "timeout_seconds": 600,
        "fail_reason": null,
        "created_at": "2018-07-05T14:09:40.092Z",
        "updated_at": "2018-07-05T14:09:40.137Z"
    },
    "confirmation_actions": [
        {
            "id": "d198c09a-6713-4fa3-ba75-187a409bf2b5",
            "created_at": "2018-07-05T14:09:40.106Z",
            "action_name": "start",
            "actor": "merchant",
            "executed": null,
            "error_message": null
        }
    ]
}

Phone-MOTO-Secure

This strategy works similarly to the Email-MOTO-Secure by including 3D-Secure verification in its pipeline. However, it processes the confirmation through an sms message instead of an email message. Similarly to Email-MOTO-Secure, this process requires the consumer to confirm credit card and order details and agree with the disclaimer before proceeding. After submitting its agreement and confirm the transaction, the API response will additionally receive the results for the 3D-Secure process with verdict.

To trigger an Phone-MOTO-Secure confirmation process, you must make an authenticated request by using the following URL.

POST https://confirmation-api.paycertify.com/api/confirmations

Parameter Type Presence Description Example
confirmation_template_id uuid Required A template ID that relates to this confirmation strategy. 63693de5-8a19-4233-b382-c75f0c6b31aa
phone_number string Required The user’s phone number that you want to confirm (in E.164 format) +11231231234
timeout_seconds string Optional Timeout in seconds (default 300 seconds) 300
callback_url string Optional The callback URL http://hooks.my.com/paycertify
Field Type Description Example
id uuid The confirmation ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. States available are idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process_name string The selected process strategy name phone_moto_secure
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. States available are: idle, generating_token, sending_sms, waiting_token, waiting_agreement, finished, failed waiting_agreement
process.phone_number string Email +11231231234
process.timeout_seconds string Time in seconds 300
process.fail_reason string A fail description when process fails Delivery Error
process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Action ID ce388e8a-300a-4833-b716-48f85251b839
confirmation_actions.*.created_at datetime Action created at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Action name start
confirmation_actions.*.actor string Action’s actor merchant
confirmation_actions.*.executed string If action is executed or not true
confirmation_actions.*.error_message string Error message Delivery Error
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'confirmation_template_id=15be8861-597a-4b7b-a0aa-b7486ba3de7e' \
  --form 'timeout_seconds=600' \
  --form 'phone_number=+11231231234'

Responds with:

{
    "id": "ca8d77c9-4477-4f48-bbea-9bc52264e74d",
    "created_at": "2018-07-05T14:09:40.098Z",
    "updated_at": "2018-07-05T14:09:40.110Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "phone_moto_secure",
    "process": {
        "id": "df3a192a-33d2-4d98-8e2d-29709c73e840",
        "state": "waiting_token",
        "phone_number": "+11231231234",
        "timeout_seconds": 600,
        "fail_reason": null,
        "created_at": "2018-07-05T14:09:40.092Z",
        "updated_at": "2018-07-05T14:09:40.137Z"
    },
    "confirmation_actions": [
        {
            "id": "d198c09a-6713-4fa3-ba75-187a409bf2b5",
            "created_at": "2018-07-05T14:09:40.106Z",
            "action_name": "start",
            "actor": "merchant",
            "executed": null,
            "error_message": null
        }
    ]
}

Listing confirmations

You can have access to the complete list of confirmations by reaching the following endpoint:

GET https://confirmation-api.paycertify.com/api/confirmations

Field Type Description Example
confirmations.*.id uuid The confirmation ID baa88e8a-300a-4833-b716-48f85251b839
confirmations.*.created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
confirmations.*.updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
confirmations.*.state string Status of this confirmation request. The possible states are: idle, processing, confirmed, refused, failed, confirmations.*.expired processing
confirmations.*.callback_url string The provided callback URL http://hooks.my.com/paycertify
confirmations.*.process_name string The selected process strategy name email_ecommerce
confirmations.*.process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
confirmations.*.process.state string Process-specific state. waiting_response
confirmations.*.process.email_address string Email example@domain.com
confirmations.*.process.timeout_seconds string Time in seconds 300
confirmations.*.process.fail_reason string A fail description when process fails Delivery Error
confirmations.*.process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
confirmations.*.process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmations.*.confirmation_actions.*.id uuid Action ID ce388e8a-300a-4833-b716-48f85251b839
confirmations.*.confirmation_actions.*.created_at datetime Action created at date 2018-07-05T14:09:40.106Z
confirmations.*.confirmation_actions.*.action_name string Action name start
confirmations.*.confirmation_actions.*.actor string Action’s actor merchant
confirmations.*.confirmation_actions.*.executed string If action is executed or not true
confirmations.*.confirmation_actions.*.error_message string Error message Delivery Error
curl --request GET \
  --url 'https://confirmation-api.paycertify.com/api/confirmations' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \

Responds with:

{
    "id": "ca8d77c9-4477-4f48-bbea-9bc52264e74d",
    "created_at": "2018-07-05T14:09:40.098Z",
    "updated_at": "2018-07-05T14:09:40.110Z",
    "state": "processing",
    "callback_url": null,
    "process_name": "email_ecommerce",
    "process": {
        "id": "df3a192a-33d2-4d98-8e2d-29709c73e840",
        "state": "waiting_response",
        "email_address": "example@domain.com",
        "timeout_seconds": 60,
        "fail_reason": null,
        "created_at": "2018-07-05T14:09:40.092Z",
        "updated_at": "2018-07-05T14:09:40.137Z"
    },
    "confirmation_actions": [
        {
            "id": "d198c09a-6713-4fa3-ba75-187a409bf2b5",
            "created_at": "2018-07-05T14:09:40.106Z",
            "action_name": "start",
            "actor": "merchant",
            "parameters": {
                "email_address": "example@domain.com",
                "timeout_seconds": "60"
            },
            "executed": null,
            "error_message": null
        }
    ]
}

Showing confirmations

Under your Fraud Portal account settings, you can define a postback URL to receive fraud data as a POST to perform any sort of automated rules that your business logic requires. These postbacks happen whenever a new transaction is created through the API.

GET https://confirmation-api.paycertify.com/api/confirmations/{confirmation_id}

Field Type Description Example
id uuid The confirmation ID baa88e8a-300a-4833-b716-48f85251b839
created_at datetime Created at date/time 2018-05-12T21:07:59.508Z
updated_at datetime Updated at date/time 2018-05-12T21:07:59.508Z
state string Status of this confirmation request. The possible states are: idle, processing, confirmed, refused, failed, expired processing
callback_url string The provided callback URL http://hooks.my.com/paycertify
process_name string The selected process strategy name email_ecommerce
process.id uuid Process-specific ID baa88e8a-300a-4833-b716-48f85251b832
process.state string Process-specific state. waiting_response
process.email_address string Email example@domain.com
process.timeout_seconds string Time in seconds 300
process.fail_reason string A fail description when process fails Delivery Error
process.created_at datetime Process-specific created at date 2018-07-05T14:09:40.106Z
process.updated_at datetime Process-specific updated at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.id uuid Action ID ce388e8a-300a-4833-b716-48f85251b839
confirmation_actions.*.created_at datetime Action created at date 2018-07-05T14:09:40.106Z
confirmation_actions.*.action_name string Action name start
confirmation_actions.*.actor string Action’s actor merchant
confirmation_actions.*.executed string If action is executed or not true
confirmation_actions.*.error_message string Error message Delivery Error
curl --request GET \
  --url 'https://confirmation-api.paycertify.com/api/confirmations/baa88e8a-300a-4833-b716-48f85251b839' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \

Responds with:

{
    "id": "3c86e137-1e59-4af5-bf9d-8f6b2970d4f9",
    "created_at": "2018-07-05T14:55:36.171Z",
    "updated_at": "2018-07-05T15:04:15.043Z",
    "state": "confirmed",
    "callback_url": null,
    "process_name": "phone_ecommerce",
    "process": {
        "id": "e8ef69e8-c50d-41ce-b306-a281217cb024",
        "state": "finished",
        "phone_number": "+5531992274225",
        "timeout_seconds": 540,
        "fail_reason": null,
        "user_response": "confirm",
        "token": "176cca1822cd0f3a23732fdbbb0ed62deefdbdd3",
        "nonce": "36615003",
        "merchant_id": "48a872f9-9389-4047-be85-a38d291e62b3",
        "created_at": "2018-07-05T14:55:36.165Z",
        "updated_at": "2018-07-05T15:04:15.038Z"
    },
    "confirmation_actions": [
        {
            "id": "152283ba-3959-4871-8f87-2a246995c17f",
            "created_at": "2018-07-05T14:55:36.179Z",
            "action_name": "start",
            "actor": "merchant",
            "parameters": {
                "phone_number": "+5531992274225",
                "timeout_seconds": "540"
            },
            "executed": null,
            "error_message": null
        },
        {
            "id": "a1c8bd51-84b6-4f5b-a467-69f9268d9300",
            "created_at": "2018-07-05T15:04:15.030Z",
            "action_name": "confirm",
            "actor": "user",
            "parameters": {
                "id": "e8ef69e8-c50d-41ce-b306-a281217cb024",
                "token": "176cca1822cd0f3a23732fdbbb0ed62deefdbdd3",
                "action_name": "confirm"
            },
            "executed": null,
            "error_message": null
        }
    ]
}

Confirmation Templates

As a confirmation process involves communication with the end-users, the messages traded with them are designed to be customizable on layout, content and branding. You must create and configure at least one template for any confirmation process to be used (listed below).

Confirmation Process process_name
Email-Ecommerce email_ecommerce
Email-MOTO email_moto
Email-MOTO-Secure email_moto_secure
Phone-Ecommerce phone_ecommerce
Phone-MOTO phone_moto
Phone-MOTO-Secure phone_moto_secure

Creating templates

To create a new template, you have to send a POST request to the URL below, by informing the parameter process_name with the one associated to the desired confirmation process (see table above).

POST https://confirmation-api.paycertify.com/api/confirmation_templates

Parameter Type Presence Description Example
process_name string required Type of process to confirm email_ecommerce, email_moto, phone_ecommerce, phone_moto, email_moto_secure, phone_moto_secure
Field Type Description Example  
id uuid The template ID 63693de5-8a19-4233-b382-c75f0c6b31aa  
process_name string Type of process to confirm email_ecommerce, email_moto, phone_ecommerce, phone_moto, email_moto_secure, phone_moto_secure  
active boolean Status of this template true  
message_templates.*.message_key string A mnemonic that identifies the message email_body  
message_templates.*.content string The message’s content. Words between curly-brackets `` are variables that will be replaced by their values in the actual messages. -  
message_templates.*.content_type string Message content type. Possible values are text and html text  
message_templates.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-07-04T19:52:22.787Z
message_templates.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-07-04T19:52:22.789Z
curl --request POST \
  --url 'https://confirmation-api.paycertify.com/api/confirmation_templates' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form 'process_name=email_moto'

Responds with:

{
    "id": "63693de5-8a19-4233-b382-c75f0c6b31aa",
    "process_name": "email_moto",
    "active": true,
    "message_templates": [
        {
            "message_key": "email_body",
            "content": "Hello, . This is a confirmation message. Please confirm it by clicking <a href=''>this link</a>",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.787Z",
            "updated_at": "2018-07-04T19:52:22.787Z"
        },
        {
            "message_key": "agreement",
            "content": "<p>By confirming this order you agree with the disclaimer mentioned above.</p><a href=''>click this link</a>.",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.789Z",
            "updated_at": "2018-07-04T19:52:22.789Z"
        },
        {
            "message_key": "thank_you",
            "content": "Thank you.",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.790Z",
            "updated_at": "2018-07-04T19:52:22.790Z"
        }
    ]
}

Updating templates

You can update your template by using the URL below. Currently the only parameter that can be updated is active (true/false). The message templates contained in each template can be altered by following these instructions.

PUT https://confirmation-api.paycertify.com/api/confirmation_templates/{confirmation_template_id}

Parameter Type Presence Description Example
active boolean required   true, false
Field Type Description Example  
id uuid The template ID 63693de5-8a19-4233-b382-c75f0c6b31aa  
process_name string Type of process to confirm email_ecommerce, email_moto, phone_ecommerce, phone_moto, email_moto_secure, phone_moto_secure  
active boolean Status of this template true  
message_templates.*.message_key string A mnemonic that identifies the message email_body  
message_templates.*.content string The message’s content. Words between curly-brackets `` are variables that will be replaced by their values in the actual messages. -  
message_templates.*.content_type string Message content type. Possible values are text and html text  
message_templates.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-07-04T19:52:22.787Z
message_templates.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-07-04T19:52:22.789Z
curl --request PUT \
  --url https://confirmation-api.paycertify.com/api/confirmation_templates/63693de5-8a19-4233-b382-c75f0c6b31aa \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \
  --form active=false

Responds with:

{
    "id": "63693de5-8a19-4233-b382-c75f0c6b31aa",
    "process_name": "email_moto",
    "active": false,
    "message_templates": [
        {
            "message_key": "email_body",
            "content": "Hello, . This is a confirmation message. Please confirm it by clicking <a href=''>this link</a>",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.787Z",
            "updated_at": "2018-07-04T19:52:22.787Z"
        },
        {
            "message_key": "agreement",
            "content": "<p>By confirming this order you agree with the disclaimer mentioned above.</p><a href=''>click this link</a>.",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.789Z",
            "updated_at": "2018-07-04T19:52:22.789Z"
        },
        {
            "message_key": "thank_you",
            "content": "Thank you.",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.790Z",
            "updated_at": "2018-07-04T19:52:22.790Z"
        }
    ]
}

Showing templates

Use the following URL to gather information of a specific template object.

GET https://confirmation-api.paycertify.com/api/confirmation_templates/{confirmation_template_id}

Field Type Description Example  
id uuid The template ID 63693de5-8a19-4233-b382-c75f0c6b31aa  
process_name string Type of process to confirm email_ecommerce, email_moto, phone_ecommerce, phone_moto, email_moto_secure, phone_moto_secure  
active boolean Status of this template true  
message_templates.*.message_key string A mnemonic that identifies the message email_body  
message_templates.*.content string The message’s content. Words between curly-brackets `` are variables that will be replaced by their values in the actual messages. -  
message_templates.*.content_type string Message content type. Possible values are text and html text  
message_templates.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-07-04T19:52:22.787Z
message_templates.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-07-04T19:52:22.789Z
curl --request GET \
  --url https://confirmation-api.paycertify.com/api/confirmation_templates/63693de5-8a19-4233-b382-c75f0c6b31aa \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \

Responds with:

{
    "id": "63693de5-8a19-4233-b382-c75f0c6b31aa",
    "process_name": "email_moto",
    "active": false,
    "message_templates": [
        {
            "message_key": "email_body",
            "content": "Hello, . This is a confirmation message. Please confirm it by clicking <a href=''>this link</a>",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.787Z",
            "updated_at": "2018-07-04T19:52:22.787Z"
        },
        {
            "message_key": "agreement",
            "content": "<p>By confirming this order you agree with the disclaimer mentioned above.</p><a href=''>click this link</a>.",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.789Z",
            "updated_at": "2018-07-04T19:52:22.789Z"
        },
        {
            "message_key": "thank_you",
            "content": "Thank you.",
            "content_type": "html",
            "created_at": "2018-07-04T19:52:22.790Z",
            "updated_at": "2018-07-04T19:52:22.790Z"
        }
    ]
}

Listing templates

Use the following URL to gather all available templates.

GET https://confirmation-api.paycertify.com/api/confirmation_templates

Field Type Description Example  
confirmation_templates.*.id uuid The template ID 63693de5-8a19-4233-b382-c75f0c6b31aa  
confirmation_templates.*.process_name string Type of process to confirm email_ecommerce, email_moto, phone_ecommerce, phone_moto, email_moto_secure, phone_moto_secure  
confirmation_templates.*.active boolean Status of this template true  
confirmation_templates.*.message_templates.*.message_key string A mnemonic that identifies the message email_body  
confirmation_templates.*.message_templates.*.content string The message’s content. Words between curly-brackets `` are variables that will be replaced by their values in the actual messages. -  
confirmation_templates.*.message_templates.*.content_type string Message content type. Possible values are text and html text  
confirmation_templates.*.message_templates.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-07-04T19:52:22.787Z
confirmation_templates.*.message_templates.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-07-04T19:52:22.789Z
curl --request GET \
  --url https://confirmation-api.paycertify.com/api/confirmation_templates \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \

Responds with:

{
    "confirmation_templates": [
        {
            "id": "debc0209-8e89-4b4d-b748-72e1b925a09c",
            "process_name": "phone_moto",
            "active": true,
            "message_templates": [
                {
                    "message_key": "sms_body",
                    "content": "This is a confirmation message. Please confirm it by accessing this link: ",
                    "content_type": "text",
                    "created_at": "2018-07-04T19:51:47.979Z",
                    "updated_at": "2018-07-04T19:51:47.979Z"
                },
                {
                    "message_key": "agreement",
                    "content": "<p>By confirming this order you agree with the disclaimer mentioned above.</p><a href=''>click this link</a>.",
                    "content_type": "html",
                    "created_at": "2018-07-04T19:51:47.981Z",
                    "updated_at": "2018-07-04T19:51:47.981Z"
                },
                {
                    "message_key": "thank_you",
                    "content": "Thank you.",
                    "content_type": "html",
                    "created_at": "2018-07-04T19:51:47.984Z",
                    "updated_at": "2018-07-04T19:51:47.984Z"
                }
            ]
        },
        {
            "id": "63693de5-8a19-4233-b382-c75f0c6b31aa",
            "process_name": "email_moto",
            "active": false,
            "message_templates": [
                {
                    "message_key": "email_body",
                    "content": "Hello, . This is a confirmation message. Please confirm it by clicking <a href=''>this link</a>",
                    "content_type": "html",
                    "created_at": "2018-07-04T19:52:22.787Z",
                    "updated_at": "2018-07-04T19:52:22.787Z"
                },
                {
                    "message_key": "agreement",
                    "content": "<p>By confirming this order you agree with the disclaimer mentioned above.</p><a href=''>click this link</a>.",
                    "content_type": "html",
                    "created_at": "2018-07-04T19:52:22.789Z",
                    "updated_at": "2018-07-04T19:52:22.789Z"
                },
                {
                    "message_key": "thank_you",
                    "content": "Thank you.",
                    "content_type": "html",
                    "created_at": "2018-07-04T19:52:22.790Z",
                    "updated_at": "2018-07-04T19:52:22.790Z"
                }
            ]
        }
    ]
}

Confirmation Messages

The confirmation messages are those ones that will be delivered to the end-user in all steps that involves communication with it. When a confirmation template is created it carries default values for all the messages. These default values might be updated in order to allow a better look-and-feel and branding.

Updating message templates

To update a message template, use the following URL:

PUT https://confirmation-api.paycertify.com/api/confirmation_templates/{confirmation_template_id}/message_templates/{message_key}

Parameter Type Presence Description Example
confirmation_template_id uuid required Confirmation Template ID -
message_key string required Message template identifier email_body
content string required The message’s content text
content_type string required Message content type html
Field Type Description Example  
message_key string Message template identifier email_body  
content string The message’s content Hello.  
content_type string The message’s content text  
created_at datetime - Time that event was created, on ISO 8601 UTC 2018-07-04T19:52:22.787Z
updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-07-04T19:52:22.789Z
curl --request PUT \
  --url 'https://confirmation-api.paycertify.com/api/confirmation_templates/63693de5-8a19-4233-b382-c75f0c6b31aa/message_templates/email_body' \
  --header 'Authorization: Bearer ' \
  --header 'Cache-Control: no-cache' \
  --form 'content=This is a confirmation message. Please confirm it by clicking this '

Responds with:

{
    "message_key": "email_body",
    "content": "This is a confirmation message. Please confirm it by clicking this ",
    "content_type": "html",
    "created_at": "2018-07-04T19:52:22.787Z",
    "updated_at": "2018-07-05T18:54:41.838Z"
}

Showing message templates

Use the following URL to retrieve information of a specific message template:

GET https://confirmation-api.paycertify.com/api/confirmation_templates/{confirmation_template_id}/message_templates/{message_key}

Parameter Type Presence Description Example
confirmation_template_id uuid required Confirmation Template ID 2f05a68b-b3ae-4728-aeff-80ec648df2e0
message_key string required Message template identifier email_body
Field Type Description Example  
message_key string Message template identifier agreement  
content string The message’s content Hello.  
content_type string The message’s content text  
created_at datetime - Time that event was created, on ISO 8601 UTC 2018-07-04T19:52:22.787Z
updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-07-04T19:52:22.789Z
curl --request GET \
  --url 'https://confirmation-api.paycertify.com/api/confirmation_templates/63693de5-8a19-4233-b382-c75f0c6b31aa/message_templates/agreement' \
  --header 'Authorization: Bearer D28A17DFD326A2E255DC4C69C17C2451446A7EC8' \
  --header 'Cache-Control: no-cache' \

Responds with:

{
    "message_key": "agreement",
    "content": "<p>By confirming this order you agree with the disclaimer mentioned above.</p><a href=''>click this link</a>.",
    "content_type": "html",
    "created_at": "2018-07-04T19:52:22.789Z",
    "updated_at": "2018-07-04T19:52:22.789Z"
}