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: POST /v1/money-movement/transfers
  ach -->> +sb: 200 OK
  ach ->> +sb: Llama al prepare debit 
 status: prepare
    Note over sb,ach: POST /v1/debits
  sb -->> +ach: 200 OK
  sb ->> +sb: Reserva de fondos
  sb ->> +ach: Confirma preparación del debit
status: prepared
  Note over ach,sb: POST /v1/money-movement/transfers/{id}/status
  ach -->> -sb: 200 OK
  ach ->> -sb: Llama al commit debit 
 status: commit
  Note over ach,sb: POST /v1/debits/{idDebit}/commit
  sb ->> +sb: Realiza débito de fondos
   sb ->>+ach: Confirma débito
Status: comited
Note over sb,ach: POST /v1/money-movement/transfers/{id}/status
ach -->> +sb: 200 OK

ach ->> -sb: Confirma estado final
status: completed
  Note over ach,sb: PUT v1/transfers/{id} 
  sb -->> +ach: 200 OK

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

A continuación, se detalla la información requerida para la implementación y puesta en marcha del servicio para la preparación del débito en la Entidad Origen.

Dominio: URL Base Entidad

POST /v1/debits

Campos de entrada preparación del débito

{
  "meta": {
    "id": "debf4f70-c30d-4f27-95e6-2f96b91c0001",
    "status": "prepare"
  },
  "data": {
    "debitId": "9d2f9ed9-7fdb-4d3b-a7bf-8cd1a8e50001",
    "movementType": "B2P-TRANSFER",
    "amountInformation": {
      "amount": 2500000.00,
      "currency": "COP"
    },
    "source": {
      "personType": "LEGAL",
      "document": {
        "number": "900123456",
        "type": "NIT"
      },
      "fullName": "COMERCIALIZADORA ABC SAS",
      "accountInformation": {
        "accountId": "200012345678",
        "accountType": "CCTE",
        "financialInstitutionId": 900123456
      }
    },
    "target": {
      "personType": "NATURAL",
      "document": {
        "number": "1020304050",
        "type": "CC"
      },
      "firstName": "CARLOS",
      "firstLastName": "RAMIREZ",
      "accountInformation": {
        "accountId": "3001234567",
        "accountType": "CAHO",
        "financialInstitutionId": 860987654
      }
    }
  }
}

HTTP/1.1 200 OK 
Content-Length: 0

Dominio: https://bank.apihub.crt.achcolombia.com.co

POST v1/money-movement/transfer/{id}/status

curl --location 'https://url_ach/v1/money_movement/transfers/{id}/status' \
--header 'hash: 695ffdf84f0dad0c19e3b8b09a4565246c156d747ffb26149e4c2dc5d3b66ca1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{
    "meta": {
        "requestId": "45cdaa41-b567-4057-9fb7-7240efdfb437",
        "version": "1.0.0",
        "timestamp": "2026-06-15T14:27:28.001"
    },
    "data": {
        "movementType": "P2P-TRANSFER",
        "status": "failed",
        "creationDateTime": "2026-06-15T14:27:28.001",
        "debitId": "deb_03rgXTmRB7aI7jomy",
        "coreId": "13456278395678906789"
    },
    "custom": {
        "error": {
            "code": "bridge.account-not-found",
            "description": "1039: Cuenta no encontrada"
        }
    }
}'

HTTP/1.1 200 OK 
Content-Length: 0

Dominio: URL Base Entidad

POST v1/debits/{idDebit}/abort

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

{
  "meta": {
    "id": "debf4f70-c30d-4f27-95e6-2f96b91c0001",
    "status": "abort"
  },
  "data": {
    "debitId": "9d2f9ed9-7fdb-4d3b-a7bf-8cd1a8e50001",
    "movementType": "B2P-TRANSFER",
    "amountInformation": {
      "amount": 2500000.00,
      "currency": "COP"
    },
    "source": {
      "personType": "LEGAL",
      "document": {
        "number": "900123456",
        "type": "NIT"
      },
      "fullName": "COMERCIALIZADORA ABC SAS",
      "accountInformation": {
        "accountId": "200012345678",
        "accountType": "CCTE",
        "financialInstitutionId": 900123456
      }
    },
    "target": {
      "personType": "NATURAL",
      "document": {
        "number": "1020304050",
        "type": "CC"
      },
      "firstName": "CARLOS",
      "firstLastName": "RAMIREZ",
      "accountInformation": {
        "accountId": "3001234567",
        "accountType": "CAHO",
        "financialInstitutionId": 860987654
      }
    }
  }
}

HTTP/1.1 200 OK
Content-Length: 0

Dominio: https://bank.apihub.crt.achcolombia.com.co

POST v1/money-movement/transfers/{id}/status

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

{
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "version": "1.0.0",
    "timestamp": "2026-08-20T14:30:00-05:00"
  },
  "data": {
    "movementType": "P2P-TRANSFER",
    "status": "aborted",
    "creationDateTime": "2026-08-20T14:35:20-05:00",
    "debitId": "dbt-3f8d8b9a-1234-4567-89ab-123456789abc",
    "coreId": "CORE-987654321"
  }
}

HTTP/1.1 200 OK 
Content-Length: 0

Dominio: https://bank.apihub.crt.achcolombia.com.co

POST v1/money-movement/transfers/{id}/status

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

{
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "version": "1.0.0",
    "timestamp": "2026-08-20T14:30:00-05:00"
  },
  "data": {
    "movementType": "P2P-TRANSFER",
    "status": "prepared",
    "creationDateTime": "2026-08-20T14:35:20-05:00",
    "debitId": "dbt-3f8d8b9a-1234-4567-89ab-123456789abc",
    "coreId": "CORE-987654321"
  }
}

HTTP/1.1 200 OK 
Content-Length: 0

Dominio: URL Base Entidad

POST v1/debits/{idDebit}/commit

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

{
  "meta": {
    "id": "debf4f70-c30d-4f27-95e6-2f96b91c0001",
    "status": "commit"
  },
  "data": {
    "debitId": "9d2f9ed9-7fdb-4d3b-a7bf-8cd1a8e50001",
    "movementType": "B2P-TRANSFER",
    "amountInformation": {
      "amount": 2500000.00,
      "currency": "COP"
    },
    "source": {
      "personType": "LEGAL",
      "document": {
        "number": "900123456",
        "type": "NIT"
      },
      "fullName": "COMERCIALIZADORA ABC SAS",
      "accountInformation": {
        "accountId": "200012345678",
        "accountType": "CCTE",
        "financialInstitutionId": 900123456
      }
    },
    "target": {
      "personType": "NATURAL",
      "document": {
        "number": "1020304050",
        "type": "CC"
      },
      "firstName": "CARLOS",
      "firstLastName": "RAMIREZ",
      "accountInformation": {
        "accountId": "3001234567",
        "accountType": "CAHO",
        "financialInstitutionId": 860987654
      }
    }
  }
}

HTTP/1.1 200 OK
Content-Length: 0

Dominio: https://bank.apihub.crt.achcolombia.com.co

POST v1/money-movement/transfers/{id}/status

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

{
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "version": "1.0.0",
    "timestamp": "2026-08-20T14:30:00-05:00"
  },
  "data": {
    "movementType": "P2P-TRANSFER",
    "status": "comited",
    "creationDateTime": "2026-08-20T14:35:20-05:00",
    "debitId": "dbt-3f8d8b9a-1234-4567-89ab-123456789abc",
    "coreId": "CORE-987654321"
  }
}

HTTP/1.1 200 OK
Content-Length: 0

Dominio: URL Base entidad

PUT /v1/transfers/{id}

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "creationDateTime": "2026-08-21T10:15:30-05:00",
    "movementType": "P2P-TRANSFER"
  }
}

HTTP/1.1 200 OK
Content-Length: 0