Cómo debitar al usuario origen

Débito al usuario origen

El endpoint de débito se invoca al inicio del procesamiento de una transferencia, con el objetivo de debitar la cuenta del usuario origen. Este endpoint debe garantizar que la cuenta esté activa y sea válida, y debe reservar los fondos necesarios para que la operación pueda ejecutarse.

En ACH En Línea, una operación de débito se representa como una acción de tipo COMMIT DEBIT. Si esta acción se marca como COMPLETED exitosamente, pero más adelante ocurre un error en el procesamiento, ACH En Línea ejecutará una operación opuesta (de tipo crédito) para revertir el movimiento de saldo y restablecer el estado original de la cuenta.

Proceso de débito paso a paso

A continuación, se describe detalladamente el flujo de procesamiento para una transferencia tipo regulada, enfocándonos en la etapa de débito al usuario origen. Este flujo se ejecuta en múltiples etapas, combinando interacciones entre ACH En Línea y el banco originador, tanto en fases síncronas como asincrónicas.

El objetivo principal de este proceso es asegurar que los fondos del usuario origen estén disponibles y sean reservados o debitados correctamente antes de avanzar con el resto de la operación. El flujo también contempla los mecanismos necesarios para revertir movimientos en caso de errores, así como el cumplimiento de los tiempos regulatorios.

A continuación, se detallan las acciones involucradas, junto con ejemplos prácticos y consideraciones técnicas relevantes.

sequenceDiagram
    autonumber
    participant sb as Entidad Origen
    participant ach as ACH En Línea

    sb ->> +ach: Creación de la tx
    Note over ach,sb: /v1/money-movements/transfers
    ach ->> +sb: Llama al prepare debit
    Note over sb,ach: /v1/debits
    sb -->> -ach: 200 OK
    sb ->> +sb: Reserva de fondos
    alt las validaciones no se cumplen
        sb ->> -ach: Envía rechazo
    end
    sb ->> +ach: Confirma preparación debit
    Note over ach,sb: /v1/money-movements/transfers/{id}/status
    ach ->> -sb: 200 OK
    ach ->> -sb: Llama al commit debit
    Note over ach,sb: /v1/debits/{idDebit}/commit
    sb ->> +sb: Realiza débito de fondos
    sb -->> -ach: 200 OK

1. ACH En Línea llama al banco origen para procesar la operación de preparación del débito

ACH En Línea inicia el proceso mediante una solicitud POST al endpoint v1/debits del banco origen, con la información completa de la transferencia.

Campos de entrada preparación del débito

Request preparación del débito

curl --location 'https://url_participante/v1/debits' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdW
FyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQ iOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

Data:

{
    "meta": {
        "id": "string",
        "status": "string"
    },
    "data": {
        "debitId": "string",
        "movementType": ["lista"],
        "amountInformation": {
            "amount": "decimal",
            "currency": ["lista"],
            "creationDateTime": "2026-05-15T14:30:00Z"
        },
        "source": {
            "personType": ["lista"],
            "document": {
                "number": "string",
                "type": ["lista"],
                "fullName": "string",
                "firstName": "string",
                "secondName": "string",
                "firstLastName": "string",
                "secondLastName": "string"
            },
            "spbviCode": ["lista"],
            "accountInformation": {
                "accountId": "string",
                "accountType": ["lista"],
                "financialInstitutionId": "entero"
            }
        },
        "target": {
            "personType": ["lista"],
            "document": {
                "number": "string",
                "type": ["lista"],
                "fullName": "string",
                "firstName": "string",
                "secondName": "string",
                "firstLastName": "string",
                "secondLastName": "string"
            },
            "targetSpbviCode": ["lista"],
            "alias": {
                "aliasType": ["lista"],
                "aliasValue": "string"
            },
            "accountInformation": {
                "accountId": "string",
                "accountType": ["lista"],
                "financialInstitutionId": "entero"
            },
            "qr": {
                "qrId": "string"
            }
        }
    }
}'

2. La Entidad Participante origen envía respuesta al llamado de preparación del débito

La Entidad Participante confirma la recepción de la instrucción para preparación del débito.

Response preparación del débito

HTTP/1.1 200 OK
Content-Length: 0

3. Reserva de fondos

La Entidad Participante asegura la reserva de fondos al usuario origen.

4. Procesar rechazo de la transferencia

En caso de que la Entidad Origen no logre procesar la preparación del débito, la transferencia debe rechazarse. Por ende, la Entidad debe enviar el respectivo rechazo vía POST al endpoint v1/money-movements/transfers/{id}/status

Campos de entrada rechazo

Campos de entrada rechazo (Body)

Request rechazo

curl --location 'https://url_ach/v1/money-movements/transfers/{id}/status' \
--header 'x-hash: 695ffdf84f0dad0c19e3b8b09a4565246c156d747ffb26149e4c2dc5d3b66ca1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyS
WQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQ iOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

{
    "data": {
        "status": "REJECTED",
        "creationDateTime": "2026-05-15T14:30:00Z",
        "coreId": "string",
        "operation": "string"
    }
}

Campos de salida rechazo

Response rechazo

{
    "data": {
        "id": "string",
        "status": "REJECTED",
        "creationDateTime": "2026-05-15T14:30:00Z",
        "movementType": ["lista"]
    }
}

5. Confirma preparación del débito

La Entidad Participante envía la confirmación de la preparación del débito a ACH En Línea. Solicitud POST al endpoint v1/money-movements/transfers/{id}/status

 

Campos de entrada confirmación preparación débito

 

Campos de entrada confirmación de la preparación del débito (header)

Campos de entrada confirmación del débito (body)

Request confirmación de la preparación del débito

curl --location 'https://url_ach/v1/money-movements/transfers/{id}/status' \
--header 'x-hash: 695ffdf84f0dad0c19e3b8b09a4565246c156d747ffb26149e4c2dc5d3b66ca1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQ iOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

{
    "data": {
        "status": "string",
        "creationDateTime": "2026-05-15T14:30:00Z",
        "coreId": "string",
        "operation": "string"
    }
}

6. ACH En Línea envía respuesta al llamado de confirmación de preparación del débito

Una vez ACH En Línea reciba la confirmación de la preparación del débito por parte de la Entidad Origen, ACH En Línea utiliza el servicio POST: https://url_participante/v1/debits/{idDebit}/commit expuesto por la Entidad Origen para que se deje en firme el débito al usuario origen. El idDebit corresponde al enviado por ACH En Línea en el request de preparación del débito.

Campos de salida enviados por ACH al recibir confirmación de preparación del débito

Response enviados por ACH al recibir confirmación de preparación del débito

{
    "data": {
        "id": "string",
        "status": "string",
        "creationDateTime": "2026-05-15T14:30:00Z",
        "movementType": ["lista"]
    }
}

7. ACH En Línea llama al banco origen para procesar la operación commit del débito

ACH En Línea ejecuta la solicitud POST al endpoint v1/debits{idDebit}/commit del banco origen para dejar en firme el débito al usuario.

 

Campos de entrada commit del débito

Request commit debit

curl --location 'https://url_participante/v1/debits/{idDebit}/commit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vL
XVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQ iOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

{
    "meta": {
        "id": "string",
        "status": "string"
    },
    "data": {
        "debitId": "string",
        "movementType": ["lista"],
        "amountInformation": {
            "amount": "decimal",
            "currency": ["lista"]
        },
        "source": {
            "personType": ["lista"],
            "document": {
                "number": "string",
                "type": ["lista"],
                "fullName": "string",
                "firstName": "string",
                "secondName": "string",
                "firstLastName": "string",
                "secondLastName": "string"
            },
            "spbviCode": ["lista"],
            "accountInformation": {
                "accountId": "string",
                "accountType": ["lista"],
                "financialInstitutionId": "entero"
            }
        },
        "target": {
            "personType": ["lista"],
            "document": {
                "number": "string",
                "type": ["lista"],
                "fullName": "string",
                "firstName": "string",
                "secondName": "string",
                "firstLastName": "string",
                "secondLastName": "string"
            },
            "targetSpbviCode": ["lista"],
            "alias": {
                "aliasType": ["lista"],
                "aliasValue": "string"
            },
            "accountInformation": {
                "accountId": "string",
                "accountType": ["lista"],
                "financialInstitutionId": "entero"
            },
            "qr": {
                "qrId": "string"
            }
        }
    }
}

 

8. Entidad Participante Origen deja en firme el débito.

La Entidad Participante deja en firme el débito o en su defecto, procesa el débito al usuario origen.

9. La Entidad Participante origen envía respuesta al llamado de commit del débito

Una vez la Entidad Participante origen efectúa el proceso del débito al usuario origen. Envía la respuesta al llamado del commit del débito.

 

Response commit del débito

HTTP/1.1 200 OK
Content-Length: 0