# SafraPay
The merchant has the ability to set up credit card transaction routing on **Carat Portal** by various payment methods, one of which is SafraPay.
This page will use the nomenclature "**SafraPay**" to reference routing in Carat Portal.
Thus, the store can configure **Carat Portal** so that transactions made with VISA cards, for example, are routed by **SafraPay** while those made with MASTERCARD are routed by CIELO.
## Carat Portal Interfaces Supported for Integration
You can use the following interfaces for integration with SafraPay routing:
- REST Payment
- REST Pre-authorization
- HTML Payment
- HTML Pre-authorization
- REST Cancel
- Cancel via Portal
## Authorizers allowed
The following authorizers are supported by SafraPay routing:
- VISA
- MASTERCARD
- ELO
- AMERICAN EXPRESS
- HIPERCARD
## Required Credentials
**The store must obtain from SafraPay the credentials listed below**, and pass them on to Software Express or register as explained later in this document.
[block:parameters]
{
"data": {
"h-0": "Field",
"h-1": "Description",
"h-2": "Format",
"0-0": "`merchantID`",
"0-1": "EC code registered with SafraPay.",
"0-2": "\\< 15 AN",
"1-0": "`terminalId`",
"1-1": "Terminal Identification.",
"1-2": "\\< 8 AN"
},
"cols": 3,
"rows": 2,
"align": [
"center",
"center",
"center"
]
}
[/block]
> **Important for HTML Payment**: In the event that a merchant authorizer has not registered these credentials, that authorizer will not be displayed on the credit card selection screen during the payment transaction.
## Registration of information through the Carat Portal Merchant's Portal
The merchant himself can register the information obtained with SafraPay on the Carat Portal Merchant's Portal. For this purpose, the merchant must select the authorizer and enter the editing screen as in the example shown below:
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/0162bf5293f2ffff3e7a35ad0f20144f6dcca321d9d3bdc9a39b1307d8873f00-roteamento-safrapay-portal.png",
null,
"Portal SafraPay"
],
"align": "center"
}
]
}
[/block]
Check more details about [Merchant's Portal](portal-lojista-introducao.md).
## Flows
This section will present the particularities of the SafraPay transactional flow.
### REST / HTML Payment
Listed below are the fields that are differentiated and relevant to SafraPay:
#### REST Begin / HTML Init
Relevant fields in the call described in [HTML Transaction Creation Service](pagamento-html-begin.md) and [REST Transaction Creation Service](pagamento-rest-begin.md):
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"h-2": "Format",
"h-3": "Mandatory",
"0-0": "`soft_descriptor`",
"0-1": "Additional text that will be presented alongside the name of the establishment in the credit card invoice. [Learn more](soft-descriptor.md#safrapay)",
"0-2": "\\< 30 AN",
"0-3": "NO",
"1-0": "**additional_data** Element for sending additional data.",
"1-1": "",
"1-2": "",
"1-3": "",
"2-0": "`postpone_confirmation`",
"2-1": "Field that allows the store to hold the transaction as a Pending Verification, and later commit or undo it.",
"2-2": "\\< 5 A",
"2-3": "NO",
"3-0": "`transaction_initiated_by`",
"3-1": "Indicates whether the transaction was initiated by the Merchant or Buyer. Relevant when used in conjunction with, for example, recurring transactions that are initiated by the merchant.
Allowed values:
`customer` - Transaction initiated by Buyer.
` merchant` - Transaction initiated by the merchant.",
"3-2": "\\< 8 AN",
"3-3": "NO",
"4-0": "`total_order_amount`",
"4-1": "Final amount of purchase.",
"4-2": "\\< 8 AN",
"4-3": "NO",
"5-0": "`tax_amount`",
"5-1": "Amount of the tax.",
"5-2": "\\< 8 AN",
"5-3": "NO",
"6-0": "**additional_data.payer** Element for submitting buyer data.",
"6-1": "",
"6-2": "",
"6-3": "",
"7-0": "`id`",
"7-1": "Buyer ID.",
"7-2": "\\< 200 AN",
"7-3": "NO",
"8-0": "`name`",
"8-1": "Name of buyer.
Note: Name concatenation with last name cannot exceed 255 characters.",
"8-2": "\\< 200 AN",
"8-3": "NO",
"9-0": "`surname`",
"9-1": "Buyer Last Name.
Note: Concatenation of first name with last name cannot exceed 255 characters.",
"9-2": "\\< 200 AN",
"9-3": "NO",
"10-0": "`identification_number`",
"10-1": "Buyer Identification Number.",
"10-2": "\\< 200 AN",
"10-3": "NO",
"11-0": "`identification_type`",
"11-1": "Identification type informed by the buyer (ID, CPF, etc.).",
"11-2": "\\< 200 AN",
"11-3": "NO",
"12-0": "`email`",
"12-1": "Buyer's email.",
"12-2": "\\< 255 AN",
"12-3": "NO",
"13-0": "**additional_data.
payer.phones\\[]** Only 1 phone will be passed on to Safrapay.",
"13-1": "",
"13-2": "",
"13-3": "",
"14-0": "`ddi`",
"14-1": "Phone IDD.",
"14-2": "\\< 255 AN",
"14-3": "NO",
"15-0": "`ddd`",
"15-1": "Phone DDD.",
"15-2": "\\< 15 AN",
"15-3": "NO",
"16-0": "`number`",
"16-1": "Telephone number.",
"16-2": "\\< 50 AN",
"16-3": "NO",
"17-0": "**additional_data.
shipment.receiver_address** Element for sending shipping address data.",
"17-1": "",
"17-2": "",
"17-3": "",
"18-0": "`street_name`",
"18-1": "Delivery address.",
"18-2": "\\< 255 AN",
"18-3": "NO",
"19-0": "`street_number`",
"19-1": "Shipping Address Number.",
"19-2": "\\< 15 AN",
"19-3": "NO",
"20-0": "`complement`",
"20-1": "Supplement of shipping address.",
"20-2": "\\< 50 AN",
"20-3": "NO",
"21-0": "`county`",
"21-1": "Neighborhood of shipping address.",
"21-2": "\\< 150 AN",
"21-3": "NO",
"22-0": "`zip_code`",
"22-1": "Zip code of shipping address. Ex .: 21241-140.",
"22-2": "\\< 9 AN",
"22-3": "NO",
"23-0": "`city`",
"23-1": "City of shipping address.",
"23-2": "\\< 50 AN",
"23-3": "NO",
"24-0": "`state`",
"24-1": "State of shipping address.",
"24-2": "= 2 AN",
"24-3": "NO",
"25-0": "`country`",
"25-1": "Country of delivery address according to the AN 3166-1. Ex. BRA",
"25-2": "= 3 AN",
"25-3": "NO",
"26-0": "**additional_data.
billing_data.address** Element for submitting billing address data.",
"26-1": "",
"26-2": "",
"26-3": "",
"27-0": "`street_name`",
"27-1": "Billing address.",
"27-2": "\\< 255 AN",
"27-3": "NO",
"28-0": "`street_number`",
"28-1": "Billing Address Number.",
"28-2": "\\< 15 AN",
"28-3": "NO",
"29-0": "`complement`",
"29-1": "Supplement of billing address.",
"29-2": "\\< 50 AN",
"29-3": "NO",
"30-0": "`county`",
"30-1": "Neighborhood of billing address.",
"30-2": "\\< 150 AN",
"30-3": "NO",
"31-0": "`zip_code`",
"31-1": "Zip code of billing address. Ex .: 21241-140.",
"31-2": "\\< 9 AN",
"31-3": "NO",
"32-0": "`city`",
"32-1": "City of billing address.",
"32-2": "\\< 50 AN",
"32-3": "NO",
"33-0": "`state`",
"33-1": "State of billing address.",
"33-2": "= 2 AN",
"33-3": "NO",
"34-0": "`country`",
"34-1": "Country of billing address according to the AN 3166-1. Ex. BRA",
"34-2": "= 3 AN",
"34-3": "NO",
"35-0": "**additional_data.items\\[]** Element for submitting data for buyer's products.",
"35-1": "",
"35-2": "",
"35-3": "",
"36-0": "`title`",
"36-1": "Product's name.",
"36-2": "\\< 255 AN",
"36-3": "NO",
"37-0": "`quantity`",
"37-1": "Quantity of the product to be purchased.",
"37-2": "\\< 15 N",
"37-3": "NO",
"38-0": "`id`",
"38-1": "Merchant code identifier of the product.",
"38-2": "\\< 255 AN",
"38-3": "NO",
"39-0": "`unit_price`",
"39-1": "Unit price of the product in cents.",
"39-2": "\\< 15 N",
"39-3": "NO",
"40-0": "`discount_amount`",
"40-1": "Discount amount in cents.",
"40-2": "\\< 12 AN",
"40-3": "NO"
},
"cols": 4,
"rows": 41,
"align": [
null,
"left",
"center",
"center"
]
}
[/block]
> Currently, SafraPay does not allow installments with interest from the card issuer, so the `installments_type` field cannot receive the value` 3` and the value `6`.
### Payment Execution
Relevant fields in the call described in the [Payment Service](pagamento-rest-dopayment.md):
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"h-2": "Format",
"h-3": "Mandatory",
"0-0": "**external_authentication** This element receives MPI authentication fields.",
"0-1": "",
"0-2": "",
"0-3": "",
"1-0": "`eci`",
"1-1": "_Eletronic Commerce Indicator_ – indica o nível de segurança da transação com autenticação do dono do cartão",
"1-2": "\\< 3 N",
"1-3": "NO",
"2-0": "`xid`",
"2-1": "Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat Portal",
"2-2": "\\< 40 N",
"2-3": "NO",
"3-0": "`cavv`",
"3-1": "_Cardholder Authentication Verification Value_ - Código que indica o resultado da autenticação do dono do cartão.",
"3-2": "\\< 40 N",
"3-3": "NO",
"4-0": "`cavv_key_indicator`",
"4-1": "Indicador de 2 digitos utilizado pela bandeira ELO.",
"4-2": "\\< 2 N",
"4-3": "NO",
"5-0": "`unpredictable_number`",
"5-1": "Indicador numérico utilizado pela bandeira ELO.",
"5-2": "-",
"5-3": "NO",
"6-0": "`auth_tracking_number`",
"6-1": "Indicador numérico utilizado pela bandeira ELO.",
"6-2": "-",
"6-3": "NO"
},
"cols": 4,
"rows": 7,
"align": [
null,
"left",
"center",
"center"
]
}
[/block]
Among the response fields of the [Payment Service](pagamento-rest-dopayment.md), the field `issuer` will be filled with the card's brand code that was recognized in the payment. Below is the list of codes and brand:
| Code | Brand |
| :-----: | :----------------- |
| `1` | VISA (credit) |
| `20002` | VISA (debit) |
| `2` | MASTERCARD |
| `20001` | MASTERCARD (debit) |
| `4` | AMEX |
| `12` | HIPERCARD (credit) |
| `20037` | HIPERCARD (debit) |
| `31` | ELO (credit) |
| `20032` | ELO (debit) |
### Payment confirmation
You can confirm a lower value than authorizations created [via HTML](pagamento-html-begin.md) and [via REST](pagamento-rest-begin.md) using the `additional_data.postpone_confirmation` field equal to `true`.
To do this, send in the [REST confirmation call](pagamento-rest-confirm.md) the desired `amount`:
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"h-2": "Format",
"h-3": "Mandatory",
"0-0": "`confirm`",
"0-1": "This field must be sent with the value `true` if you wish to confirm the transaction, or `false` if you wish to undo the payment.",
"0-2": "\\< 5 T/F",
"0-3": "YES",
"1-0": "`amount`",
"1-1": "Value in cents of the amount to be confirmed. If not sent, the full amount of the transaction will be confirmed.",
"1-2": "\\< 12 N",
"1-3": "NO"
},
"cols": 4,
"rows": 2,
"align": [
null,
null,
null,
null
]
}
[/block]
### Recurrence
SafraPay accepts transaction recurrence indication parameters. To do this, send in the REST payment call the `acquirer.recurrency` field with the value `true`.
For more information, see the [REST Payment Service page](pagamento-rest-dopayment.md).
### Pre-Authorization
Normally, the installment of a pre-authorization is processed in the [Pre-authorization Capture Service](pre-autorizacao-rest-capture.md), but SafraPay is one of the exceptions.
Therefore, the `installments` and `installment_type` fields will be processed when effectuate the pre-authorization or initializing a pre-authorization transaction.
For more details on filling in this field, see:
- [REST Pre-authorization - Creation Service](pre-autorizacao-rest-begin.md).
- [REST Pre-Authorization - Effectuation Service](pre-autorizacao-rest-doPreAuthorization.md)
- [HTML Pre-authorization - Initializing a pre-authorization transaction](pre-autorizacao-html.md)
> Currently, SafraPay does not allow installments with interest from the card issuer, so the `installments_type` field cannot use the value` 3` and the value `6` (IATA).
### Cancellation
The cancellation of a transaction can be done on the [Merchant's Portal](portal-lojista-cancelamento-transacao.md) or via [Web Service REST](cancelamento-rest-quickstart.md). Transactions made on the current day of cancellation (D + 0) or other days (D + N) may be canceled. The merchant can cancel payment transactions that have been confirmed as well as those that have not yet been confirmed.
You can also cancel lower amounts than the original payment for both confirmed and unconfirmed transactions. For unconfirmed transactions, only a partial cancellation can be made.
SafraPay's cancellation transaction processing takes place in the window between 0am until 6am. We advise that cancellations are not made during this period.
### IATA
The SafraPay routing supports payments with IATA (International Air Transport Association).
Therefore, the `departure_tax` and` first_installment` fields will be processed in the ["Payment REST - Transaction Creation Service"](pagamento-rest-begin.md).