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 credito) 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 Validaciones no se cumplen
        sb ->> +ach: Envía rechazo
        Note over sb,ach: validación
    end
    
    ach ->> +sb: Confirmación preparación
    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_entidad/v1/debits' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

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"
      }
    }
  }
}'

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 via POST al endpoint v1/money-movements/transfers/{id}/status.

 

Campos de entrada rechazo

 

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

Campos de entrada confirmación del débito (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.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

{
  "data": {
    "status": "string",
    "creationDateTime": "fecha",
    "coreId": "string",
    "operation": "string"
  }
}

Campos de salida rechazo

Response rechazo

{
  "data": {
    "id": "string",
    "status": "string",
    "creationDateTime": "fecha",
    "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 preparación del débito (header)

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

Request confirmación de 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.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

{
  "data": {
    "status": "string",
    "creationDateTime": "fecha",
    "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 la Entidad Participante envía la confirmación de preparación del débito. ACH En Línea envía la respuesta a dicho llamado.

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 debit

Request commit debit

curl --location 'https://url_participante/v1/debits/{idDebit}/commit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.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