Placetopay Docs

POST/gateway/otp/generate

OTP generation (Ecuador only)

This service is consumed if the OTP is required for the card provided by the client (requireOtp is true) and the user must be allowed to enter the OTP to send it later in the processing service, as an example this is captured in the interface redirection

Request

Name
locale
Type
string
is optional
Description
Name
auth
Type
Autenticación
is optional
Description
Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
Name
login
Type
string
is optional
Description
Name
tranKey
Type
string
is optional
Description
Name
nonce
Type
string
is optional
Description
Name
seed
Type
string
is optional
Description
Name
instrument
Type
Instrument
is optional
Description
Structure that contains information about the means of payment to be used in a transaction. This structure is variable according to the request that is generated. Each service requires that one or another data be used.
Name
card
Type
Card
is optional
Description
Structure containing card information.
Name
number
Type
string
is Required
REQUIRED
Description
Max length:20
Name
expiration
Type
string
is optional
Description
Example:12/22
Pattern:^[01]\d\/\d{2}$
Name
cvv
Type
string
is optional
Description
Name
installments
Type
number
is optional
Description
Name
account
Type
Account
is optional
Description
Structure that contains bank account information.
Name
bankName
Type
string
is optional
Description
Name of the bank of the account to be processed
Max length:30
Name
bankCode
Type
string
is Required
REQUIRED
Description
Code that identifies the bank on the network
Max length:17
Name
accountType
Type
string
is Required
REQUIRED
Description
Account type
Allowed values:SAVDDACCD
Name
accountNumber
Type
string
is Required
REQUIRED
Description
Account number
Max length:17
Name
franchise
Type
string
is optional
Description
Max length:20
Name
verificationCode
Type
string
is optional
Description
The verificationCode is a JSON Web Signature (JWS). It is intended to be the instrument for verifying the status of the account
Example:eyJhbGciOiJSUzI1NiJ9.eyJhY2NvdW50SGFzaCI6ImM5YWM2ZjFhZDhjNDA3Y2ZjNzMyNDljNTE2MTJjNTdmMWQxZGNiNTA4YjE4ZGJlYWE1MWQ0NDI5NjBjMjUwNDUyMzY4ZTg2YmUzMWQ3MDMxMDY4ZDM2MjM2NzVjYzhkYTUzNzhhODNmMTUwZjg5OTczOTBiZTEyMGU1ZmExN2RhIiwib25UZXN0Ijp0cnVlLCJzZXJ2aWNlIjoibW9jayIsImlkIjo0MDB9.dFMY4EwCrWq9EBmERFkKCoLHExPH4vgaCgnZaqB_mf8n3Sv6Qnu6Pb79onluX1OZecmYmBuHqZ_ykKXWSD4RMZSpckYFCiO3mlcJKI4qb91COhl_c2qXxYJuLEdbLfGlzf0k8-oJgFcO9gAS1Xm0hpTP4iiXF6st1hFwlfR3fpX4rr-bTsKgMvRSReMuxa0Vs92DykfqUR_3udlc0DFCPB9ZTaSqeRNHFAPAWNniUPWURQlW5c9J9xcyKTgKGzfI1_7h2I4ALQeRifptE2nC-HZtEMwtcToNh7hn0oL9lNFXnXGK9sWKORcyWKVfpEChS8z30UfX6kOhU6fp_qUwmA
Name
token
Type
Token
is optional
Description
Structure that contains the token information associated with the card. For entry, only the token or subtoken and the cvv are necessary if it is an operation where the user is present. For output if all data is returned when tokenizing.
Name
token
Type
string
is optional
Description
Code generated to identify the card in the system
Max length:64
Min length:64
Name
subtoken
Type
string
is optional
Description
Alternate code generated to identify the card
Max length:16
Min length:16
Name
franchise
Type
string
is optional
Description
Franchise code associated with the token (Only as a response, it is not necessary to send it)
Allowed values:visavisa_electronamexmastercodensadinersjbcdiscoverriscredencialcomfamacolsubsidiofalabellaelosomostuyaexitoalkostomaestromefiaath_card
Name
franchiseName
Type
string
is optional
Description
Name
issuerName
Type
string
is optional
Description
Name
lastDigits
Type
string
is optional
Description
Name
validUntil
Type
string
is optional
Description
Name
cvv
Type
string
is optional
Description
CVV requested from the user in case it is present in the operation
Max length:4
Min length:3
Name
credit
Type
Credit
is optional
Description
Structure that contains information on the type of credit
Name
code
Type
string
is optional
Description
Name
type
Type
string
is optional
Description
Name
groupCode
Type
string
is optional
Description
Name
installment
Type
integer
is optional
Description
Name
threeDS
Type
object
is optional
Description
Name
version
Type
string
is Required
REQUIRED
Description
Allowed values:v2v2x
Name
id
Type
number
is optional
Description
This value only applies if the validation was done with the Placetopay 3DS service
Name
enrolled
Type
string
is Required
REQUIRED
Description
Reports whether the card is registered in 3DS
Allowed values:YNU
Min length:1
Name
authenticated
Type
string
is Required
REQUIRED
Description
Allowed values:YNUAICDR
Max length:1
Min length:1
Name
eci
Type
string
is Required
REQUIRED
Description
Authentication result indicator generated by e-commerce.
Allowed values:020100050607
Min length:1
Name
cavv
Type
string
is Required
REQUIRED
Description
Authentication value for the franchise generated by the ACS. (3DS field authenticationValue).
Example:AJkBABIWcQAAAAM5FwIzdGiYeHM
Max length:28
Min length:28
Nullable:Yes
Name
xid
Type
string
is Required
REQUIRED
Description
DS Transaction ID (3DS dsTransID field).
Min length:1
Name
extra
Type
object
is optional
Description
Name
transStatusReason
Type
string
is optional
Description
Provides information about the status of the transaction.
Nullable:Yes
Name
acsTransId
Type
string
is optional
Description
Unique transaction identifier generated by the ACS.
Example:37a7b6e0-fd58-4e38-98de-79c70c526a47
Name
threeDSServerTransID
Type
string
is optional
Description
Unique transaction identifier generated by the 3DS Server.
Example:eadd3a60-b870-41d0-977f-921b3dbe6323/MkGJDl2Y5E=
Name
validSignature
Type
boolean
is optional
Description
Name
otp
Type
string
is optional
Description
Name
pinPad
Type
PinPad
is optional
Description
Structure containing PinPad service information
Name
transactionId
Type
string
is optional
Description
Name
positions
Type
string
is optional
Description
Name
pinBlock
Type
string
is optional
Description
Name
length
Type
integer
is optional
Description
Name
pin
Type
string
is optional
Description
Receives the PIN code when it is flat or when it is a PinBlock
Example:0B880E2326F6409E
Max length:20
Min length:2
Name
redirection
Type
Redirection
is optional
Description
It represents a redirect payment method, meaning that it requires the user to be sent to another URL to complete the process.
Name
paymentMethod
Type
string
is optional
Description
Allowed values:_PSE_BTNBCBTNBCPGEFT
Name
returnURL
Type
string
is optional
Description
URL so that once the payment process is completed, control is returned (when applicable)
Example:http://your-site.com/your-return-route
Format:uri
Max length:250
Name
processURL
Type
string
is optional
Description
URL to which the client must be sent to continue the process, it is provided by the service
Format:uri
Max length:250
Name
additional
Type
object
is optional
Description
Estructura para relacionar datos adicionales en el proceso.
Name
bankCode
Type
string
is optional
Description
Código que identifica al banco en la red.
Example:1007
Name
userType
Type
string
is optional
Description
Example:person
Name
kount
Type
Kount
is optional
Description
Manages specific information to use with the Kount risk filter
Name
session
Type
string
is Required
REQUIRED
Description
Identifier of this operation in Kount, it must be unique per transaction
Name
type
Type
string
is optional
Description
Describes the type of operation that is being handled in the session to define the additional fields to be sent
Allowed values:airlinesoat
Name
pocket
Type
string
is optional
Description
Card pocket used for payment

Solicitud

POST

/gateway/otp/generate

curl -X "POST" https://api-co-dev.placetopay.ws/gateway/otp/generate \
-H "Content-Type: application/json" \
-d '{
    "locale": "es_CO",
    "auth": {
        "login":"c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    },
    "payer": {
        "name": "John",
        "email": "[email protected]"
    },
    "payment": {
        "reference": "1234567890",
        "amount": {
            "currency": "USD",
            "total": "3"
        }
    },
    "instrument": {
        "card": {
            "number": "4110760000000008",
            "expiration": "12/20",
            "cvv": "123"
        }
    },
    "ipAddress": "127.0.0.1",
    "userAgent": "Testing"
}'

Response

Name
status
Type
Status
is optional
Description
Structure that contains information about a request or payment, informing its current status.
Name
status
Type
string
is optional
Description
Allowed values:OKFAILEDAPPROVEDAPPROVED_PARTIALPARTIAL_EXPIREDREJECTEDPENDINGPENDING_VALIDATIONPENDING_PROCESSREFUNDEDREVERSEDERRORUNKNOWNMANUALDISPUTE
Name
reason
Type
string
is optional
Description
Max length:4
Min length:1
Name
message
Type
string
is optional
Description
Name
date
Type
string
is optional
Description
Example:2021-09-21T09:34:48-05:00
Name
provider
Type
string
is optional
Description

Respuesta

{
    "status": {
        "status": "OK",
        "reason": "00",
        "message": "La petición se ha procesado correctamente",
        "date": "2021-09-21T14:52:28-05:00"
    },
    "provider": "INTERDIN"
}

POST/gateway/otp-validate

OTP validation (Ecuador only)

It allows you to validate that the OTP provided matches the one sent by the provider and will provide a signature that serves to authenticate the transaction

Important Note

It is necessary to send the returned value as signature in the response as instrument.otp in the processing request so that it is recorded in the transaction

Request

Name
locale
Type
string
is optional
Description
Name
auth
Type
Autenticación
is optional
Description
Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
Name
login
Type
string
is optional
Description
Name
tranKey
Type
string
is optional
Description
Name
nonce
Type
string
is optional
Description
Name
seed
Type
string
is optional
Description
Name
instrument
Type
Instrument
is optional
Description
Structure that contains information about the means of payment to be used in a transaction. This structure is variable according to the request that is generated. Each service requires that one or another data be used.
Name
card
Type
Card
is optional
Description
Structure containing card information.
Name
number
Type
string
is Required
REQUIRED
Description
Max length:20
Name
expiration
Type
string
is optional
Description
Example:12/22
Pattern:^[01]\d\/\d{2}$
Name
cvv
Type
string
is optional
Description
Name
installments
Type
number
is optional
Description
Name
account
Type
Account
is optional
Description
Structure that contains bank account information.
Name
bankName
Type
string
is optional
Description
Name of the bank of the account to be processed
Max length:30
Name
bankCode
Type
string
is Required
REQUIRED
Description
Code that identifies the bank on the network
Max length:17
Name
accountType
Type
string
is Required
REQUIRED
Description
Account type
Allowed values:SAVDDACCD
Name
accountNumber
Type
string
is Required
REQUIRED
Description
Account number
Max length:17
Name
franchise
Type
string
is optional
Description
Max length:20
Name
verificationCode
Type
string
is optional
Description
The verificationCode is a JSON Web Signature (JWS). It is intended to be the instrument for verifying the status of the account
Example:eyJhbGciOiJSUzI1NiJ9.eyJhY2NvdW50SGFzaCI6ImM5YWM2ZjFhZDhjNDA3Y2ZjNzMyNDljNTE2MTJjNTdmMWQxZGNiNTA4YjE4ZGJlYWE1MWQ0NDI5NjBjMjUwNDUyMzY4ZTg2YmUzMWQ3MDMxMDY4ZDM2MjM2NzVjYzhkYTUzNzhhODNmMTUwZjg5OTczOTBiZTEyMGU1ZmExN2RhIiwib25UZXN0Ijp0cnVlLCJzZXJ2aWNlIjoibW9jayIsImlkIjo0MDB9.dFMY4EwCrWq9EBmERFkKCoLHExPH4vgaCgnZaqB_mf8n3Sv6Qnu6Pb79onluX1OZecmYmBuHqZ_ykKXWSD4RMZSpckYFCiO3mlcJKI4qb91COhl_c2qXxYJuLEdbLfGlzf0k8-oJgFcO9gAS1Xm0hpTP4iiXF6st1hFwlfR3fpX4rr-bTsKgMvRSReMuxa0Vs92DykfqUR_3udlc0DFCPB9ZTaSqeRNHFAPAWNniUPWURQlW5c9J9xcyKTgKGzfI1_7h2I4ALQeRifptE2nC-HZtEMwtcToNh7hn0oL9lNFXnXGK9sWKORcyWKVfpEChS8z30UfX6kOhU6fp_qUwmA
Name
token
Type
Token
is optional
Description
Structure that contains the token information associated with the card. For entry, only the token or subtoken and the cvv are necessary if it is an operation where the user is present. For output if all data is returned when tokenizing.
Name
token
Type
string
is optional
Description
Code generated to identify the card in the system
Max length:64
Min length:64
Name
subtoken
Type
string
is optional
Description
Alternate code generated to identify the card
Max length:16
Min length:16
Name
franchise
Type
string
is optional
Description
Franchise code associated with the token (Only as a response, it is not necessary to send it)
Allowed values:visavisa_electronamexmastercodensadinersjbcdiscoverriscredencialcomfamacolsubsidiofalabellaelosomostuyaexitoalkostomaestromefiaath_card
Name
franchiseName
Type
string
is optional
Description
Name
issuerName
Type
string
is optional
Description
Name
lastDigits
Type
string
is optional
Description
Name
validUntil
Type
string
is optional
Description
Name
cvv
Type
string
is optional
Description
CVV requested from the user in case it is present in the operation
Max length:4
Min length:3
Name
credit
Type
Credit
is optional
Description
Structure that contains information on the type of credit
Name
code
Type
string
is optional
Description
Name
type
Type
string
is optional
Description
Name
groupCode
Type
string
is optional
Description
Name
installment
Type
integer
is optional
Description
Name
threeDS
Type
object
is optional
Description
Name
version
Type
string
is Required
REQUIRED
Description
Allowed values:v2v2x
Name
id
Type
number
is optional
Description
This value only applies if the validation was done with the Placetopay 3DS service
Name
enrolled
Type
string
is Required
REQUIRED
Description
Reports whether the card is registered in 3DS
Allowed values:YNU
Min length:1
Name
authenticated
Type
string
is Required
REQUIRED
Description
Allowed values:YNUAICDR
Max length:1
Min length:1
Name
eci
Type
string
is Required
REQUIRED
Description
Authentication result indicator generated by e-commerce.
Allowed values:020100050607
Min length:1
Name
cavv
Type
string
is Required
REQUIRED
Description
Authentication value for the franchise generated by the ACS. (3DS field authenticationValue).
Example:AJkBABIWcQAAAAM5FwIzdGiYeHM
Max length:28
Min length:28
Nullable:Yes
Name
xid
Type
string
is Required
REQUIRED
Description
DS Transaction ID (3DS dsTransID field).
Min length:1
Name
extra
Type
object
is optional
Description
Name
transStatusReason
Type
string
is optional
Description
Provides information about the status of the transaction.
Nullable:Yes
Name
acsTransId
Type
string
is optional
Description
Unique transaction identifier generated by the ACS.
Example:37a7b6e0-fd58-4e38-98de-79c70c526a47
Name
threeDSServerTransID
Type
string
is optional
Description
Unique transaction identifier generated by the 3DS Server.
Example:eadd3a60-b870-41d0-977f-921b3dbe6323/MkGJDl2Y5E=
Name
validSignature
Type
boolean
is optional
Description
Name
otp
Type
string
is optional
Description
Name
pinPad
Type
PinPad
is optional
Description
Structure containing PinPad service information
Name
transactionId
Type
string
is optional
Description
Name
positions
Type
string
is optional
Description
Name
pinBlock
Type
string
is optional
Description
Name
length
Type
integer
is optional
Description
Name
pin
Type
string
is optional
Description
Receives the PIN code when it is flat or when it is a PinBlock
Example:0B880E2326F6409E
Max length:20
Min length:2
Name
redirection
Type
Redirection
is optional
Description
It represents a redirect payment method, meaning that it requires the user to be sent to another URL to complete the process.
Name
paymentMethod
Type
string
is optional
Description
Allowed values:_PSE_BTNBCBTNBCPGEFT
Name
returnURL
Type
string
is optional
Description
URL so that once the payment process is completed, control is returned (when applicable)
Example:http://your-site.com/your-return-route
Format:uri
Max length:250
Name
processURL
Type
string
is optional
Description
URL to which the client must be sent to continue the process, it is provided by the service
Format:uri
Max length:250
Name
additional
Type
object
is optional
Description
Estructura para relacionar datos adicionales en el proceso.
Name
bankCode
Type
string
is optional
Description
Código que identifica al banco en la red.
Example:1007
Name
userType
Type
string
is optional
Description
Example:person
Name
kount
Type
Kount
is optional
Description
Manages specific information to use with the Kount risk filter
Name
session
Type
string
is Required
REQUIRED
Description
Identifier of this operation in Kount, it must be unique per transaction
Name
type
Type
string
is optional
Description
Describes the type of operation that is being handled in the session to define the additional fields to be sent
Allowed values:airlinesoat
Name
pocket
Type
string
is optional
Description
Card pocket used for payment
Name
payment
Type
Payment
is optional
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
reference
Type
string
is optional
Description
Max length:32
Min length:1
Name
description
Type
string
is optional
Description
Max length:250
Name
amount
Type
Amount
is optional
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
currency
Type
string
is Required
REQUIRED
Description
Allowed values:USDCOPCRCEURCADAUDGBPMXNCLP
Example:COP
Max length:3
Min length:3
Name
total
Type
number
is Required
REQUIRED
Description
Name
taxes
Type
array[TaxDetail]
is optional
Description
Name
kind
Type
string
is optional
Description
Tipo de impuesto reportado
Allowed values:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Example:valueAddedTax
Name
amount
Type
number
is optional
Description
Name
base
Type
number
is optional
Description
Name
details
Type
array[AmountDetail]
is optional
Description
Name
kind
Type
string
is optional
Description
Name
amount
Type
number
is optional
Description
Name
dispersion
Type
array[Dispersion]
is optional
Description
Name
agreement
Type
number
is optional
Description
Transaction recipient identifier. For the primary transaction site, the value must be null.
Nullable:Yes
Name
agreementType
Type
string
is optional
Description
Allowed values:AIRLINEMERCHANT
Name
amount
Type
Amount
is optional
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
currency
Type
string
is Required
REQUIRED
Description
Allowed values:USDCOPCRCEURCADAUDGBPMXNCLP
Example:COP
Max length:3
Min length:3
Name
total
Type
number
is Required
REQUIRED
Description
Name
taxes
Type
array[TaxDetail]
is optional
Description
Name
kind
Type
string
is optional
Description
Tipo de impuesto reportado
Allowed values:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Example:valueAddedTax
Name
amount
Type
number
is optional
Description
Name
base
Type
number
is optional
Description
Name
details
Type
array[AmountDetail]
is optional
Description
Name
kind
Type
string
is optional
Description
Name
amount
Type
number
is optional
Description
Name
modifiers
Type
array[PaymentModifier]
is optional
Description
Structure containing payment modifiers
Name
type
Type
string
is optional
Description
Modifier type
Allowed values:FEDERAL_GOVERNMENT
Name
code
Type
string
is optional
Description
Modifier code. When the type is FEDERAL_GOVERMENT, it represents the law number for discount.
Example:17934
Name
additional
Type
object
is optional
Description
Additional modifier information
Name
invoice
Type
string
is optional
Description
Invoice number. Required when type is FEDERAL_GOVERMENT.
Name
shipping
Type
Person
is optional
Description
Structure for relating shipping information.
Name
documentType
Type
string
is optional
Description
Type of identification document
Allowed values:CCNITRUTTIPNN
Example:CC
Max length:3
Name
Document
Type
string
is optional
Description
Identification document number.
Name
name
Type
string
is optional
Description
Names
Name
surname
Type
string
is optional
Description
Surnames
Name
company
Type
string
is optional
Description
Company
Name
email
Type
string
is optional
Description
Email.
Name
address
Type
Address
is optional
Description
Object that contains information about a person's address.
Name
street
Type
string
is optional
Description
Street
Max length:128
Name
city
Type
string
is optional
Description
City
Max length:30
Name
state
Type
string
is optional
Description
State/province/department. ISO 3166-2 code
Example:NY
Name
postalCode
Type
string
is optional
Description
Postal Code
Example:110111
Max length:10
Name
country
Type
string
is optional
Description
Country code. ISO 3166-1 alpha-2 code
Example:CO
Max length:2
Name
phone
Type
string
is optional
Description
Phone number
Example:3003003000
Max length:20
Name
mobile
Type
string
is optional
Description
Mobile phone
Name
subscription
Type
Subscription
is optional
Description
Structure that contains information about a subscription or transaction that does not require a specific amount
Name
reference
Type
string
is optional
Description
Max length:32
Name
description
Type
string
is optional
Description
Max length:254
Min length:1

Solicitud

POST

/gateway/otp-validate

curl -X "POST" https://api-co-dev.placetopay.ws/gateway/otp-validate \
-H "Content-Type: application/json" \
-d '{
    "locale": "es_CO",
    "auth": {
        "login":"c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    },
    "payer": {
        "name": "John",
        "email": "[email protected]"
    },
    "payment": {
        "reference": "1234567890",
        "amount": {
            "currency": "USD",
            "total": "3"
        }
    },
    "instrument": {
        "card": {
            "number": "4110760000000008",
            "expiration": "12/20",
            "cvv": "123"
        },
        "otp": "123456"
    },
}'

Response

Name
status
Type
Status
is optional
Description
Structure that contains information about a request or payment, informing its current status.
Name
status
Type
string
is optional
Description
Allowed values:OKFAILEDAPPROVEDAPPROVED_PARTIALPARTIAL_EXPIREDREJECTEDPENDINGPENDING_VALIDATIONPENDING_PROCESSREFUNDEDREVERSEDERRORUNKNOWNMANUALDISPUTE
Name
reason
Type
string
is optional
Description
Max length:4
Min length:1
Name
message
Type
string
is optional
Description
Name
date
Type
string
is optional
Description
Example:2021-09-21T09:34:48-05:00
Name
provider
Type
string
is optional
Description
Name
signature
Type
string
is optional
Description
Nullable:Yes
Name
validated
Type
boolean
is optional
Description

Respuesta

{
    "status": {
        "status": "OK",
        "reason": "00",
        "message": "OTP Validation successful",
        "date": "2021-09-21T15:12:01-05:00"
    },
    "provider": "INTERDIN",
    "signature": "a586077cd77ec2dbcb9b7f68b896368a",
    "validated": true
}