# Acme Citibank Brazil Payments (/guides/citi-br-payments)



This describes validations / allowed data formats for Acme payments going
through Citibank Brazil (BIC: `CITIBRBRXXX`). These will be validated by Acme and further validated by
the bank. These rules may be stricter than what the bank requires.

Field paths below match batch payloads (`payments[N].…` per inlined payment).

### Common Definitions [#common-definitions]

* SWIFT Character Set:
  * The 26 uppercase Latin letters `A`-`Z`
  * The 26 lowercase Latin letters `a`-`z`
  * The 10 digits `0`-`9`
  * Forward slash `/`
  * Hyphen `-`
  * Question mark `?`
  * Colon `:`
  * Left and right parentheses `(` `)`
  * Full stop `.`
  * Comma `,`
  * Single quote `'`
  * Plus sign `+`
  * Space <code> </code>

* Citi restrictions:
  * For SWIFT character set: do not start a field with any of the following characters: `/`, `-`, `:`

### Supported payment types (Citi Brasil) [#supported-payment-types-citi-brasil]

| Type             | Description                      | Currency | Amount / notes             |
| ---------------- | -------------------------------- | -------- | -------------------------- |
| `BR_BOLETO`      | Boleto (bank slip)               | BRL only | 1–99,999,999 (minor units) |
| `BR_UTILITY`     | Utility bill (barcode)           | BRL only | 1–99,999,999               |
| `BR_TAX_BARCODE` | Tax payment (`receiver.barCode`) | BRL only | 1–99,999,999               |
| `BR_DIPHASED`    | Diphased transfer                | BRL only | 1–99,999,999               |
| `BR_PIX`         | PIX                              | BRL only | 1–99,999,999               |

## BR\_BOLETO [#br_boleto]

| field               | pattern / charset                                     | max length   | mandatory/optional |
| ------------------- | ----------------------------------------------------- | ------------ | ------------------ |
| customerReference   | Alphanumeric                                          | 15           | M                  |
| paymentDetails      | Optional; `/PMD*` / `/LALx/` prefix rules if prefixed | 140          | O                  |
| receiver.barCode    | Numeric, 44 - 47 digits                               | 47           | M                  |
| paymentAdviceEmails | Valid email, max 1                                    | 50 per email | O                  |
| receiver.name       | SWIFT                                                 | 70           | M                  |
| receiver.taxId      | Alphanumeric                                          | 20           | M                  |
| receiver.branchId   | Numeric                                               | 8            | O                  |
| receiver.address    | SWIFT                                                 | 35 chars x 3 | O                  |

## BR\_UTILITY [#br_utility]

| field             | pattern / charset                                     | max length   | mandatory/optional |
| ----------------- | ----------------------------------------------------- | ------------ | ------------------ |
| customerReference | Alphanumeric                                          | 15           | M                  |
| paymentDetails    | Optional; `/PMD*` / `/LALx/` prefix rules if prefixed | 140          | O                  |
| receiver.barCode  | Numeric, 44 - 48 digits, starts with 8                | 48           | M                  |
| receiver.name     | SWIFT                                                 | 70           | M                  |
| receiver.bank     | Alphanumeric (BIC)                                    | 11           | O                  |
| receiver.branchId | Numeric, 4 digits                                     | 4            | O                  |
| receiver.address  | SWIFT                                                 | 35 chars x 3 | O                  |

## BR\_TAX\_BARCODE [#br_tax_barcode]

| field             | pattern / charset       | max length   | mandatory/optional |
| ----------------- | ----------------------- | ------------ | ------------------ |
| customerReference | Alphanumeric            | 15           | M                  |
| taxDate           | `yyyy-MM-dd` (optional) | 10           | O                  |
| paymentDetails    | Optional remittance     | 140          | O                  |
| receiver.barCode  | Numeric                 | 50           | M                  |
| receiver.name     | SWIFT                   | 70           | M                  |
| receiver.bank     | Alphanumeric (BIC)      | 11           | O                  |
| receiver.branchId | Numeric, 4 digits       | 4            | O                  |
| receiver.address  | SWIFT                   | 35 chars x 3 | O                  |

## BR\_DIPHASED [#br_diphased]

| field                           | pattern / charset                                     | max length   | mandatory/optional |
| ------------------------------- | ----------------------------------------------------- | ------------ | ------------------ |
| customerReference               | Alphanumeric                                          | 15           | M                  |
| paymentDetails                  | Optional; `/PMD*` / `/LALx/` prefix rules if prefixed | 140          | O                  |
| instructionForSenderBank        | Forbidden (omit)                                      | —            | —                  |
| paymentAdviceEmails             | Valid email, max 1                                    | 50 per email | O                  |
| receiver.name                   | SWIFT                                                 | 70           | M                  |
| receiver.bankAccountNumber      | Numeric, 6–10 digits                                  | 10           | M                  |
| receiver.localRoutingIdentifier | Numeric (bank code)                                   | 8            | O                  |
| receiver.taxId                  | Alphanumeric                                          | 20           | M                  |
| receiver.branchId               | Numeric                                               | 8            | M                  |
| receiver.address.line1          | SWIFT                                                 | 35           | M                  |

## BR\_PIX [#br_pix]

| field                           | pattern / charset                                     | max length   | mandatory/optional |
| ------------------------------- | ----------------------------------------------------- | ------------ | ------------------ |
| customerReference               | Alphanumeric                                          | 32           | M                  |
| paymentDetails                  | Optional; `/PMD*` / `/LALx/` prefix rules if prefixed | 140          | O                  |
| instructionForSenderBank        | Forbidden (omit)                                      | —            | —                  |
| paymentAdviceEmails             | Valid email, max 1                                    | 50 per email | O                  |
| receiver.name                   | SWIFT                                                 | 80           | M                  |
| receiver.bankAccountNumber      | Alphanumeric                                          | 34           | M                  |
| receiver.localRoutingIdentifier | Numeric (bank code)                                   | 8            | M                  |
| receiver.taxId                  | Alphanumeric                                          | 20           | M                  |
| receiver.branchId               | Numeric                                               | 8            | M                  |
| receiver.address.line1          | SWIFT                                                 | 35           | M                  |