Create payment
POST /payments
Creates a new payment for analysis
Request body
payment object
Identify the payment with a unique code that does not repeat within the same account. If not provided, a random identifier will be generated.
Payment type
purchase verifyPayment status. See the documentation for more details on possible statuses.
initiated succeeded declined failed blockedPayment currency according to the ISO 4217 standard.
Value with two decimal places. Use "." as the decimal separator.
Date and time when the payment was initiated in ISO 8601 format. If not sent, the current time will be used. The maximum period for retroactive submission (backfill) is 24 hours. Future timestamps are not allowed.
Payment method. Preferably, send all available information in this request. If some data is not available at this stage of your flow, it can be sent later through the same parameter in the update operation.
method object
Payment method type.
credit_card debit_cardcard object
Card network
visa mastercard american_express diners_club elo hipercard jcb discover otherIndicates whether the transaction was made with card present (CP) or card not present (CNP). See the card presence documentation for more information.
card_present card_not_presentFirst 8 digits of the PAN that identify the card issuer (also known as IIN)
Last 4 digits of the PAN
Information about the external server sending the request to your backend API. Make sure the data sent is from the remote server outside your security perimeter, not from intermediate servers within your infrastructure.
backend object
IPv4 or IPv6 address of the external server. If this data is not available, leave the field blank. Private addresses will be ignored in the analysis.
HTTP headers sent by the external server. If possible, send all of them. Otherwise, send at least `User-Agent`, `Accept`, `Accept-Encoding`, `Accept-Language`, and `Host`. Confidential headers used for authentication and session will be automatically removed.
Information about the user's device, if the payment was made in an online environment (web or app). Do not send this block for attempts initiated without direct user interaction (recurring renewal, for example).
device object
IPv4 or IPv6 address of the user's device. If this data is not available, leave the field blank. Private addresses will be rejected.
HTTP headers sent by the user's device in the request. If possible, send all of them. Otherwise, send at least `User-Agent`, `Accept`, `Accept-Encoding`, `Accept-Language`, and `Host`. Confidential headers used for authentication and session will be automatically removed.
User's device fingerprint.
fingerprint object
Unique identifier code of the device fingerprint.
Fingerprint collection service provider.
fingerprintjs basicInformation about the user making the payment.
user object
User identifier code.
User email. If you want analysis without personal data, provide only the domain (e.g. `gmail.com`).
Order information.
order object
Optional order identifier code (or purchase, subscription, cart, etc). Payment retries on the same order should use the same identifier to track the number of attempts. See the documentation for more details on the order code.
Merchant information. Use this field to specify the business unit, franchise, or company performing the operation.
merchant object
Identifier code of the merchant performing the operation.
Merchant country in ISO 3166-1 alpha-2 format (2 characters).
Merchant category code (MCC) according to the ISO 18245 standard.
List of transaction attempts for this payment. Required if payment `status` is `succeeded` or `declined`. Recommended for `failed` and `blocked` if there are transaction attempts.
transactions[] item
Unique transaction identifier code. See the documentation for more details on the transaction code.
Transaction attempt return status. See the documentation for more details on possible statuses.
succeeded declined failedTransaction execution time in milliseconds (1 second = 1000 milliseconds).
Date and time when the transaction was initiated in ISO 8601 format. If not sent, the current time will be used. The maximum period for retroactive submission (backfill) is 24 hours. Future timestamps are not allowed.
Information about the payment connector used in the transaction. The connector can be an acquirer, a sub-acquirer, or a gateway.
connector object
Integration code with the connector. Provide a code that represents an affiliation contract or a specific integration connection. We recommend prefixing the code with the connector type to facilitate report queries.
Connector type. See the documentation for the complete list.
Alphanumeric response code of the attempt. For credit cards in Brazil, preferably use the standard determined by ABECS normative 21. Required if `transaction.status` is `succeeded` or `declined`. Recommended for `failed` when present.
Additional metadata. For information about requirements and limits, see the documentation.
Enables payment analysis.
analyze object
Optionally specify the rule to be applied in the risk recommendation.
rule object
Rule name, as previously registered. If the specified rule does not exist or does not have an active published version, the request will not fail and the risk recommendation will be provided according to the account's default configuration.
Detects automated behavior (bots, scripts, etc.)
Responses
201Payment created successfully
payment object
Identifier code of the created payment.
Payment status.
Results of the requested analyses.
analyses object
bot_behaviour object
Recommended action based on the risk score and the configuration in the admin panel.
allow challenge denyRisk score in decimal format between `0.00` and `1.00` with two decimal places. The closer to 1, the higher the probability the payment was made by a bot. This is an informational field only. We recommend using the `action` field recommendation to implement decision-making. To simulate an arbitrary score in the test account, check the documentation.
401Invalid access credentials
errors[] item
Request field where the error occurred
Error type code
Error message
422Invalid parameters
errors[] item
Request field where the error occurred
Error type code
Error message
{
"payment": {
"id": "string",
"type": "purchase",
"status": "initiated",
"currency": "BRL",
"amount": 10.23,
"timestamp": "2024-01-01T00:00:00Z",
"method": {
"type": "credit_card",
"card": {
"network": null,
"presence": null,
"bin": null,
"last_four": null
}
},
"backend": {
"ip_address": "200.200.200.200",
"headers": {
"User-Agent": "Java-Http-Client/11.0",
"Accept": "application/json",
"EveryOtherHeader": "value"
}
},
"device": {
"ip_address": "200.200.200.200",
"headers": {
"User-Agent": "Chrome",
"Accept": "text/html,application/xhtml+xml",
"EveryOtherHeader": "value"
},
"fingerprint": {
"id": null,
"provider": null
}
},
"user": {
"id": "string",
"email": "teste@gmail.com"
},
"order": {
"id": "string"
},
"merchant": {
"id": "string",
"country": "BR",
"category_code": "7997"
},
"transactions": [
{
"id": null,
"status": null,
"duration": null,
"timestamp": null,
"connector": null
}
],
"metadata": {
"plano": "premium_1",
"categoria_do_cliente": "vip"
},
"analyze": {
"rule": {
"name": null
},
"bot_behaviour": false
}
}
}