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.

Field	Description	Format
merchantID	EC code registered with SafraPay.	< 15 AN
terminalId	Terminal Identification.	< 8 AN

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:

Check more details about Merchant's Portal.

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 and REST Transaction Creation Service:

Parameter	Description	Format	Mandatory
soft_descriptor	Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more	< 30 AN	NO
additional_data Element for sending additional data.
postpone_confirmation	Field that allows the store to hold the transaction as a Pending Verification, and later commit or undo it.	< 5 A	NO
transaction_initiated_by	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.	< 8 AN	NO
total_order_amount	Final amount of purchase.	< 8 AN	NO
tax_amount	Amount of the tax.	< 8 AN	NO
additional_data.payer Element for submitting buyer data.
id	Buyer ID.	< 200 AN	NO
name	Name of buyer. Note: Name concatenation with last name cannot exceed 255 characters.	< 200 AN	NO
surname	Buyer Last Name. Note: Concatenation of first name with last name cannot exceed 255 characters.	< 200 AN	NO
identification_number	Buyer Identification Number.	< 200 AN	NO
identification_type	Identification type informed by the buyer (ID, CPF, etc.).	< 200 AN	NO
email	Buyer's email.	< 255 AN	NO
additional_data. payer.phones[] Only 1 phone will be passed on to Safrapay.
ddi	Phone IDD.	< 255 AN	NO
ddd	Phone DDD.	< 15 AN	NO
number	Telephone number.	< 50 AN	NO
additional_data. shipment.receiver_address Element for sending shipping address data.
street_name	Delivery address.	< 255 AN	NO
street_number	Shipping Address Number.	< 15 AN	NO
complement	Supplement of shipping address.	< 50 AN	NO
county	Neighborhood of shipping address.	< 150 AN	NO
zip_code	Zip code of shipping address. Ex .: 21241-140.	< 9 AN	NO
city	City of shipping address.	< 50 AN	NO
state	State of shipping address.	= 2 AN	NO
country	Country of delivery address according to the AN 3166-1. Ex. BRA	= 3 AN	NO
additional_data. billing_data.address Element for submitting billing address data.
street_name	Billing address.	< 255 AN	NO
street_number	Billing Address Number.	< 15 AN	NO
complement	Supplement of billing address.	< 50 AN	NO
county	Neighborhood of billing address.	< 150 AN	NO
zip_code	Zip code of billing address. Ex .: 21241-140.	< 9 AN	NO
city	City of billing address.	< 50 AN	NO
state	State of billing address.	= 2 AN	NO
country	Country of billing address according to the AN 3166-1. Ex. BRA	= 3 AN	NO
additional_data.items[] Element for submitting data for buyer's products.
title	Product's name.	< 255 AN	NO
quantity	Quantity of the product to be purchased.	< 15 N	NO
id	Merchant code identifier of the product.	< 255 AN	NO
unit_price	Unit price of the product in cents.	< 15 N	NO
discount_amount	Discount amount in cents.	< 12 AN	NO

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:

Parameter	Description	Format	Mandatory
external_authentication This element receives MPI authentication fields.
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NO
xid	Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat Portal	< 40 N	NO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NO
cavv_key_indicator	Indicador de 2 digitos utilizado pela bandeira ELO.	< 2 N	NO
unpredictable_number	Indicador numérico utilizado pela bandeira ELO.	-	NO
auth_tracking_number	Indicador numérico utilizado pela bandeira ELO.	-	NO

Among the response fields of the Payment Service, 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 and via REST using the additional_data.postpone_confirmation field equal to true.

To do this, send in the REST confirmation call the desired amount:

Parameter	Description	Format	Mandatory
confirm	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.	< 5 T/F	YES
amount	Value in cents of the amount to be confirmed. If not sent, the full amount of the transaction will be confirmed.	< 12 N	NO

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.

Pre-Authorization

Normally, the installment of a pre-authorization is processed in the Pre-authorization Capture Service, 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.
• REST Pre-Authorization - Effectuation Service
• HTML Pre-authorization - Initializing a pre-authorization transaction

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 or via Web Service REST. 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".