Skip to main content

Migration Guide: From integration_key to JWS

This guide helps existing EBANX merchants migrate from the legacy integration_key authentication method to JWS (JSON Web Signature) authentication. This migration applies to all EBANX API products, including Payments, Payouts, and Transfers.

Why migrate​

The integration_key authentication method is being deprecated in favor of JWS authentication. JWS provides stronger security guarantees:

  • No shared secrets in transit — With integration_key, the same secret is included in every request body, creating potential exposure risks. With JWS, your private key never leaves your infrastructure.
  • Request integrity — Each request is cryptographically signed. Any modification to the request body invalidates the signature.
  • Non-repudiation — The origin of each API call can be verified.

What changes​

The migration involves three changes to your integration:

AspectBefore (integration_key)After (JWS)
Authentication methodintegration_key field in request bodyX-JWS-Signature HTTP header
Secret handlingShared secret sent with every requestPrivate key stays on your server
Request bodyIncludes integration_key fieldNo authentication fields in body
SetupReceive key from EBANXGenerate RSA key pair, register public key with EBANX

Migration steps​

  1. Set up JWS authentication
    ​

    Follow the JWS Integration Guide to generate your RSA key pair and register your public key with EBANX.

    After completing the setup, you will have:

    • A private key stored securely in your infrastructure
    • A public key registered with EBANX
    • A unique key identifier (kid) provided by EBANX

  2. Update your request structure
    ​

    Remove the integration_key field from your request bodies. Authentication is now handled entirely through the X-JWS-Signature header.

    Before (with integration_key):

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_integration_key",
        "payment": {
          "name": "Jose Silva",
          "email": "jose@example.com",
          "country": "br",
          "payment_type_code": "pix",
          "merchant_payment_code": "order-12345",
          "currency_code": "BRL",
          "amount_total": 100.00
        }
      }'

    After (with JWS):

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --header 'X-JWS-Signature: <YOUR_JWS_SIGNATURE>' \
      --data '{
        "payment": {
          "name": "Jose Silva",
          "email": "jose@example.com",
          "country": "br",
          "payment_type_code": "pix",
          "merchant_payment_code": "order-12345",
          "currency_code": "BRL",
          "amount_total": 100.00
        }
      }'
    public_integration_key is unchanged

    The public_integration_key used for client-side tokenization (EBANX.js) is not affected by this migration. Only the server-side integration_key is being replaced by JWS.

  3. Test in sandbox
    ​

    Test your updated integration in the sandbox environment before deploying to production.

    Verify that:

    • API requests succeed with the X-JWS-Signature header
    • The integration_key field is no longer present in request bodies
    • All your existing functionality continues to work correctly

  4. Deploy to production
    ​

    Once testing is complete, deploy your changes to production. Generate a separate production key pair if you used a different one for sandbox, and register the production public key with EBANX.

    Contact integration@ebanx.com if you need assistance during the migration process.

Migration checklist​

Before completing your migration, verify the following:

  • RSA key pair generated with at least 4096 bits
  • Public key registered with EBANX and kid received
  • Private key stored securely and not exposed
  • All API requests include X-JWS-Signature header
  • integration_key field removed from all request bodies
  • public_integration_key usage unchanged (client-side tokenization)
  • Integration tested in sandbox environment
  • Production deployment completed

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: