Skip to main content
Version: 1.0.0

banca.me API

The banca.me BNPL API is a crucial component of our Buy Now, Pay Later (BNPL) platform. It provides endpoints for operating our BNPL (Compra Ahora, Paga Depués) payment platform. This API enables merchants to seamlessly integrate BNPL payment options into their e-commerce or payment platforms.

Features​

  • Generate secure widget tokens for BNPL checkout
  • Support for multiple integration scenarios
  • Secure token management
  • Flexible configuration options
  • Pre-approval integration support
  • Customizable payment terms

Base URL​

The base URL for production API requests is:

https://api.banca.me

For integration and testing use https://beta.api.banca.me (development) or https://automation.api.banca.me (automation). See Environments.

Rate Limiting​

Cancel a BNPL loan by external transaction ID and Partially refund a BNPL loan by external transaction ID share a limit of one request every 15 seconds:

  • Their responses include the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers
  • 429 status code is returned when the limit is exceeded, with a Retry-After header and a plain-text body

Error Handling​

The API uses standard HTTP status codes. Error responses have a JSON body:

{
  "data": {
    "status": 422,
    "url": "/partner/pre-loan-request/bnpl",
    "ip": "203.0.113.10",
    "partnerId": "5f0c2a8e-1b3d-4c6e-9f7a-2d4b6c8e0a1f",
    "message": "ERR_EMAIL_IS_UNDEFINED"
  }
}
  • status: HTTP status code
  • url: path of the request
  • ip: IP address of the request
  • partnerId: partner of the API token, when the token could be decoded
  • message: error code. Only returned with status codes 422 and 500; for other status codes, use the status code and the causes listed in each endpoint
  • Other fields may be present and can be ignored

Status codes returned by this API:

  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 405: Method Not Allowed
  • 409: Conflict
  • 412: Precondition Failed
  • 413: Payload Too Large
  • 422: Unprocessable Entity
  • 429: Too Many Requests
  • 500: Internal Server Error
  • 503: Service Unavailable

Data Formats​

The API accepts and returns data in the following formats:

  • Request: application/x-www-form-urlencoded
  • Response: application/json

BNPL integration flow​

To integrate the banca.me BNPL widget:

  1. Pre-approval (optional):
  • Use the pre-approval API to check customer eligibility
  • Store the pre-approval ID for later use
  1. The widgetToken Generation:
  • Generate a widget token using this API
  • Include transaction details and pre-approval ID if available
  1. Widget Implementation:
  • Initialize the widget with the generated token
  • Handle widget events and callbacks
  • Process the final response
  1. Transaction Verification:
  • Verify the transaction status through your backend
  • Update your order status accordingly

Best Practices​

  1. Token Management
  • Generate tokens only when needed
  • Store tokens securely
  • Implement token expiration handling
  • Use HTTPS for all requests
  1. Error Handling
  • Implement proper error handling
  • Check HTTP status codes
  • Parse error messages from responses
  • Implement retry logic for temporary failures
  1. Security
  • Keep your API token secure
  • Never expose tokens in client-side code
  • Validate all input data
  • Use HTTPS for all requests
  1. Performance
  • Cache tokens when appropriate
  • Monitor rate limits
  • Implement proper error recovery
  • Optimize token generation frequency
  1. User Experience
  • Implement proper loading states
  • Show clear error messages
  • Handle edge cases gracefully
  • Provide fallback payment options

Authentication​

Partner access token provided by banca.me

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer