Pix on File Payment

Pix on File (JSR) payments require an active enrollment to be initiated.

1. Merchant initiates payment referencing the enrollment
2. System returns a FIDO2 challenge
3. Customer authenticates using their registered FIDO2 credentials
4. Payment is authorized and funds are transferred

Requirements

• EBANX Account
• API Credentials - Ensure you have your EBANX integration Key. If not, complete the Merchant Signup Form.

Payment Initiation

Pix on File Payments are initiated using the merchant_enrollment_code created during Device Linking.

Parameter	Requirement	Description
integration_key	Required	Your integration key
type	Required	Must be request
mode	Required	Must be full
payment.country	Required	Must be br
payment.currency_code	Required	Currency code
payment.amount_total	Required	Currency code
payment.merchant_payment_code	Required	Payment code
payment.order_number	Optional	Order number
payment.payment_type_code	Required	Must be pix-jsr
payment.name	Required	Customer name
payment.email	Required	Customer email
payment.document	Required	Customer document
payment.metadata.merchant_enrollment_code	Required	Unique enrollment code

Sample Request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "type": "request",
    "mode": "full",
    "payment": {
        "country": "br",
        "currency_code": "BRL",
        "amount_total": "{total_amount}",
        "merchant_payment_code": "{merchant_payment_code}",
        "order_number": "{order_number}",
        "payment_type_code": "pix-jsr",
        "name": "{user_name}",
        "email": "{user_email}",
        "document": "{user_document}",
        "metadata": {
            "merchant_enrollment_code": "{merchant_enrollment_code}"
        }
    }
}'

A successful request will return a JSON response like the one below, creating a payment request in pending status and providing the cryptographic challenge (Base64url) that must be signed by the client's FIDO2 authenticator to complete the payment.

{
  "payment": {
    "hash": "{payment_hash}",
    "country": "br",
    "merchant_payment_code": "{merchant_payment_code}",
    "order_number": "{order_number}",
    "status": "PE",
    "open_date": "{open_date}",
    "amount_br": "{amount_br}",
    "amount_ext": "{amount_ext}",
    "amount_iof": "{amount_iof}",
    "currency_rate": "{currency_rate}",
    "currency_ext": "BRL",
    "due_date": "{due_date}",
    "payment_type_code": "pix-jsr",
    "pix-jsr": {
      "id": "{id}",
      "fido_challenge": "{fido_challenge}"
    }
  },
  "status": "SUCCESS"
}

Payment Authentication

After collecting the results of the FIDO2/WebAuthn authentication performed by the customer, send a payment authentication request using the parameters below to complete the payment.

Parameter	Requirement	Description
integration_key	Required	Your integration key
hash	Required	Payment hash
risk_signals	Required	Refer to the Risk Signals section.
authentication.credentialId		Credential ID used for the signature, in Base64url format
authentication.rawCredentialId	Required	The credential ID in ArrayBuffer format (Base64url encoded)
authentication.type	Required	Must be public-key
authentication.response.clientDataJSON		Client data in JSON, encoded in Base64url
authentication.response.authenticatorData	Required	Authenticator data encoded in Base64url
authentication.response.signature	Required	Cryptographic signature of the data (the heart of authentication)
authentication.response.userHandle	Required	The opaque user identifier, encoded in Base64URL (bytes)

Sample Request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/payment/authentication' \
  --header 'Content-Type: application/json' \
  --data '{
"integration_key": "your_ebanx_integration_key",
 "hash": "{payment_hash}",
 "risk_signals": {},
 "fidoAssertion": {
  "credentialId": "{credential_id_base_64}",
  "rawCredentialId": "{credential_id_array_buffer_base_64}",
  "type": "public-key",
  "response": {
   "clientDataJSON": "{client_data_json_in_base_64}",
   "authenticatorData": "{authenticator_data_in_base_64}",
   "signature": "{cryptographic_signature}",
      "userHandle": "{user_handle}"
  }
 }
}'

A successful request will return a JSON response like the one below, confirming the payment status.

{
  "payment": {
    "hash": "{payment_hash}",
    "country": "br",
    "merchant_payment_code": "{merchant_payment_code}",
    "order_number": "{order_number}",
    "status": "CO",
    "status_date": "{status_date}",
    "open_date": "{open_date}",
    "confirm_date": "{confirm_date}",
    "amount_br": "{amount_br}",
    "amount_ext": "{amount_ext}",
    "amount_iof": "{amount_iof}",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "{due_date}",
    "payment_type_code": "pix-jsr"
  },
  "status": "SUCCESS"
}