Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Requests up to 500 enrollments in one call, from one or several merchants. Each item follows the rule of Request enrollment: the same fields, the same errors, and a repeated request comes back existing, without creating another.

Request each enrollment once, when the seller joins your base: do not include enrollments in a daily upload (see Sync guide).

POST https://api.rapidchargeback.com/api/v1/enrollments/batch
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

FieldTypeRequiredDescription
itemsarrayYesFrom 1 to 500 requests, each with the fields of Request enrollment, including its own merchant_id or merchant_ref
modeenumNopartial (default) or all_or_nothing
  • Body up to 2 MB. Above that, 413 PAYLOAD_TOO_LARGE.
  • A field other than items and mode in the envelope, or items empty or with more than 500: the whole batch is rejected with 422 VALIDATION_ERROR, saving nothing.
modeWhat happens
partialEach item is saved or rejected on its own. existing counts as success
all_or_nothingRapid checks every item first. If any fails, nothing is saved and the batch comes back 422 ENROLLMENT_BATCH_INVALID with the list of rejected items. existing does not count as a failure; ENROLLMENT_PREVIOUSLY_REJECTED does

The same identifier in two items of the batch (descriptor ignoring case, repeated spaces and spaces around *, or the same BIN + CAID): the first counts and the following ones are rejected with ENROLLMENT_DUPLICATE_IN_BATCH.

If the batch’s new requests would take your company above 20,000 enrollments waiting for approval, the whole batch is rejected with 422 ENROLLMENT_PENDING_LIMIT, saving nothing.


Terminal window
curl -X POST https://api.rapidchargeback.com/api/v1/enrollments/batch \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/json" \
-d '{
"mode": "partial",
"items": [
{ "merchant_ref": "PB-1001", "enrollment_type": "descriptor", "descriptor_value": "LOJA EXEMPLO", "descriptor_rule": "exact", "products": ["alert"] },
{ "merchant_ref": "PB-1002", "enrollment_type": "bin_caid", "bin": "424242", "caid": "123456789", "products": ["alert"] },
{ "merchant_ref": "PB-1002", "enrollment_type": "descriptor", "descriptor_value": "loja exemplo", "descriptor_rule": "exact", "products": ["alert"] }
]
}'

200 OK whenever the batch was processed, even with rejected items. Check failed and each item’s result.

{
"data": {
"total": 3,
"succeeded": 2,
"failed": 1,
"counts": { "created": 1, "existing": 1 },
"results": [
{
"index": 0,
"result": "existing",
"merchant_ref": "PB-1001",
"enrollment": {
"id": "00000000-0000-0000-0000-0000000000aa",
"merchant_id": "00000000-0000-0000-0000-000000000001",
"merchant_ref": "PB-1001",
"enrollment_type": "descriptor",
"descriptor_value": "loja exemplo",
"descriptor_rule": "exact",
"bin": null,
"caid": null,
"arn": null,
"products": {
"alert": { "status": "active", "rejection_reason": null, "approved_at": "2026-11-07T15:00:00.000Z" },
"prevention": null
},
"created_at": "2026-11-06T12:00:00.000Z",
"updated_at": "2026-11-07T15:00:00.000Z"
}
},
{
"index": 1,
"result": "created",
"merchant_ref": "PB-1002",
"enrollment": { "id": "00000000-0000-0000-0000-0000000000ab", "...": "Enrollment object" }
},
{
"index": 2,
"result": "error",
"merchant_ref": "PB-1002",
"status": 422,
"error": {
"code": "ENROLLMENT_DUPLICATE_IN_BATCH",
"message": "Descriptor \"loja exemplo\" appears more than once in the batch",
"params": { "identifier": "Descriptor \"loja exemplo\"" }
}
}
]
}
}
FieldDescription
total, succeeded, failedItems sent, accepted (created or existing) and rejected
countsHow many of each: created, existing
resultsOne per item, in the order of the array sent
results[].indexPosition of the item in the array sent, starting at 0
results[].resultcreated, existing or error
results[].merchant_refThe merchant_ref you sent in the item (null if merchant_id was sent)
results[].enrollmentOn success: the Enrollment object, the same as in Request enrollment
results[].status, results[].errorOn error: the HTTP status the item would get on its own and the error (code, message, params)
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "ENROLLMENT_BATCH_INVALID",
"message": "1 of 3 items were not accepted. Nothing was created.",
"params": { "count": 1, "total": 3 },
"details": {
"errors": [
{
"index": 2,
"code": "ENROLLMENT_DUPLICATE_IN_BATCH",
"message": "Descriptor \"loja exemplo\" appears more than once in the batch",
"params": { "identifier": "Descriptor \"loja exemplo\"" }
}
]
}
}
}
HTTP/1.1 429 Too Many Requests
Retry-After: 5
{
"error": {
"code": "BATCH_IN_PROGRESS",
"message": "Another batch from this account is still being processed. Try again in a few seconds."
}
}

Your company runs one enrollment batch at a time. A second batch sent while the first is still being saved is rejected in full: wait for Retry-After and send it again.

HTTPCodeWhen
422VALIDATION_ERRORInvalid envelope: items missing, empty, with more than 500, mode outside the list or an unknown field in the envelope
422ENROLLMENT_BATCH_INVALIDAll or nothing with some item rejected (params.count, params.total, details.errors)
422ENROLLMENT_PENDING_LIMITThe batch would take your company above 20,000 pending (params.limit)
413PAYLOAD_TOO_LARGEBody above 2 MB
429RATE_LIMIT_EXCEEDEDMore than 60 writes per minute (each batch counts as one)
429BATCH_IN_PROGRESSAnother enrollment batch from your company is still in progress
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDCompany without an approved registration, inactive or blocked
503SERVICE_UNAVAILABLETemporarily unavailable: repeat after Retry-After

  • Repeating is safe. After a 503 or a dropped connection, send the same batch: what was already saved comes back existing. If you get BATCH_IN_PROGRESS, the previous batch is still being saved: wait and repeat.
  • Send one batch after the other, not in parallel.
  • Auth, rate limit, error codes: see Authentication and Response codes.