Register a standing Bre-B alias so payers can send you COP. Only key_type: ALIAS may be registered. The alias starts with @ followed by 1-19 alphanumeric characters. PHONE, EMAIL, and USER_IDENTIFICATION return 400 invalid_field. Create is synchronous and returns status: ACTIVE. Delete removes the key.

Merchant OpenAPI is the Unified Payments contract copied as-is from CI. See Create Payin Key, List Payin Keys, Get Payin Key, and Delete Payin Key.

Identity is co_breb.beneficiary (NATURAL_PERSON or LEGAL_PERSON). List requires type=CO_BREB. Optional filters: external_ref, document_id, and key. external_ref is optional and not unique (max 64; ^[a-zA-Z0-9_-]+$), same rules as payouts. Statuses are ACTIVE and INACTIVE. Create returns 201 with ACTIVE. Delete returns 204 with an empty body. Reusing Idempotency-Key with a different body returns 400 idempotency_key_already_used. A duplicate key returns 409 payin_key_duplicate. Pay-in keys do not emit webhooks. The payin webhook for funds received on a key carries sender identity and, when present, co_breb.beneficiary_key (id is always set). Match beneficiary_key.id to the pay-in key. When that object is omitted, treat the pay-in as a first-party deposit recorded before this snapshot existed.

First-party vs third-party

Omit co_breb.beneficiary to register against the authenticated account's KYC. Retail accounts map to a natural person; institutional accounts map to a legal person.

Send beneficiary when you register a key for someone else. The object is all-or-nothing and is never merged with KYC.

More than one pay-in key may be registered for the same document.

Natural person

document_type is one of CC, CE, TI, PA, NIT. Nested natural_person is all-or-nothing: send given_name, family_name, phone_number, birth_date, email, and gender (MALE or FEMALE).

{
  "type": "CO_BREB",
  "external_ref": "client-key-natural-001",
  "co_breb": {
    "key_type": "ALIAS",
    "key": "@JUANPEREZ",
    "beneficiary": {
      "type": "NATURAL_PERSON",
      "document_type": "CC",
      "document_id": "123456789",
      "natural_person": {
        "given_name": "Juan",
        "family_name": "Perez",
        "phone_number": "3001234567",
        "birth_date": "1990-05-15",
        "email": "[email protected]",
        "gender": "MALE"
      }
    }
  }
}

Legal person

document_type is NIT only. Nested legal_person is all-or-nothing: send title, phone_number, and email. Legal person has no birth_date or gender.

{
  "type": "CO_BREB",
  "external_ref": "client-key-legal-001",
  "co_breb": {
    "key_type": "ALIAS",
    "key": "@ACMESAS",
    "beneficiary": {
      "type": "LEGAL_PERSON",
      "document_type": "NIT",
      "document_id": "900123456",
      "legal_person": {
        "title": "Acme SAS",
        "phone_number": "6015551234",
        "email": "[email protected]"
      }
    }
  }
}

Status and delete

• ACTIVE: registered and can receive funds. Returned on successful create.
• INACTIVE: Cannot receive funds.
• Delete: Delete Payin Key currently returns 204. A later get or delete of the same id returns 404.

Related

• Payment Flow — where pay-in keys sit among payouts, intents, and pay-ins.
• Webhook Notifications — payin events for funds that land on a key.