Skip to main content

Close Payment Batch Insertion

After inserting all desired settlements into the batch, use this endpoint to signal that insertion is complete and processing can begin. You can also discard the entire batch.

Where am I in the flow?

This is the 3rd step of the settlement flow. Before this step, you must have:

  1. Created the payment batch
  2. Inserted the settlements

Request​

ENDPOINT
/settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
METHOD
PUT

Path params​

ParameterTypeDescription
external_idstringThe external_id provided when creating the batch.
Request Body
{
    "batch_status": "pending_payment"
}

Body attributes​

FieldTypeRequiredDescription
batch_statusstringrequiredStatus to which the batch will be updated. See enumerators below.

batch_status enumerators:

ValueDescription
pending_paymentCloses insertion and starts batch processing.
discardedDiscards the entire batch. No settlements will be processed.

Response​

STATUS
200
Response Body
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_payment"
}

Response attributes​

FieldTypeDescription
external_idstringExternal batch key provided by the partner.
statusstringNew batch status.

Possible errors​

STATUS
404
Batch not found

The external_id provided in the URL does not match any batch registered for this fund. Verify that the identifier is correct.

{
  "title": "Payment batch not found",
  "description": "The Payment Batch with external_id {payment_batch_external_id} was not found",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado",
  "code": "SET000010"
}
STATUS
400
Invalid status

The value provided in the batch_status field is not valid. Use only pending_payment or discarded.

{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}
STATUS
400
Batch with no settlements

You attempted to close the batch, but it has no settlements inserted yet. You must insert at least one settlement before closing the batch.

{
  "title": "Payment Batch with no settlement",
  "description": "Payment batch of external_id: {payment_batch_external_id} have no settlements to be settled",
  "translation": "O lote de pagamento com identificador: {payment_batch_external_id} não possui liquidações",
  "code": "SET000017"
}

Next steps​

After closing the batch, processing starts automatically. Track the result through webhooks:

  1. Payment batch webhooks — notification when the batch is paid.
  2. Settlement webhooks — individual notification for each processed settlement.