Enroll Descriptors for Dispute Alerts

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/alert-enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "providerConfigId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.staging.payrails.io/dispute/disputes/alert-enrollments"

payload = {
    "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerConfigId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    providerId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    providerConfigId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.staging.payrails.io/dispute/disputes/alert-enrollments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.staging.payrails.io/dispute/disputes/alert-enrollments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'workspaceId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'providerId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'providerConfigId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.staging.payrails.io/dispute/disputes/alert-enrollments"

	payload := strings.NewReader("{\n  \"workspaceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerConfigId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.staging.payrails.io/dispute/disputes/alert-enrollments")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"workspaceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerConfigId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/dispute/disputes/alert-enrollments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"workspaceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerConfigId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.malformed",
      "detail": "The request has malformed syntax",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.unauthorized",
      "detail": "The request lacks necessary credentials to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
    }
  ]
}

{
  "errors": [
    {
      "id": "e7db22b3-914e-4975-928e-9edfb0885bea",
      "code": "request.forbidden",
      "detail": "The request credentials lack the required permissions to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.not-found",
      "detail": "The requested resource was not found",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.conflict",
      "detail": "The request operation is not allowed due to a conflict with the current state of the resource",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestconflict"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.rate-limit",
      "detail": "Too many requests",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "internal",
      "detail": "An internal error occurred",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#internal"
    }
  ]
}

Enroll Descriptors for Dispute Alerts

Enroll one or more merchant descriptors with a pre-chargeback alert program. Runs synchronously and returns once the provider has accepted the enrollment. Behaviour depends on the program:

Ethoca / CDRN / RDR (actionable, descriptor-based): one or more descriptors are required. The request is forwarded to the provider (Chargeblast), which assigns a merchant reference. Returns once the provider has accepted the enrollment.
VerifiINFORM / SAFE (account-level, reporting-only): no descriptors; externalReference (the provider merchant ID for that program) is required instead. No provider API call is made — the enrollment row is created locally and used to resolve incoming fraud-report alert webhooks.

Re-enrolling an existing (providerConfigId, program) pair resumes that enrollment: for actionable programs it appends new descriptors to the existing provider merchant; for account-level programs it updates the stored externalReference.

POST

https://api.staging.payrails.io

dispute

disputes

alert-enrollments

Enroll Descriptors for Dispute Alerts

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/alert-enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "providerConfigId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.staging.payrails.io/dispute/disputes/alert-enrollments"

payload = {
    "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerConfigId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    providerId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    providerConfigId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.staging.payrails.io/dispute/disputes/alert-enrollments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.staging.payrails.io/dispute/disputes/alert-enrollments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'workspaceId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'providerId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'providerConfigId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.staging.payrails.io/dispute/disputes/alert-enrollments"

	payload := strings.NewReader("{\n  \"workspaceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerConfigId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.staging.payrails.io/dispute/disputes/alert-enrollments")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"workspaceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerConfigId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/dispute/disputes/alert-enrollments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"workspaceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"providerConfigId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.malformed",
      "detail": "The request has malformed syntax",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.unauthorized",
      "detail": "The request lacks necessary credentials to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
    }
  ]
}

{
  "errors": [
    {
      "id": "e7db22b3-914e-4975-928e-9edfb0885bea",
      "code": "request.forbidden",
      "detail": "The request credentials lack the required permissions to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.not-found",
      "detail": "The requested resource was not found",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.conflict",
      "detail": "The request operation is not allowed due to a conflict with the current state of the resource",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestconflict"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.rate-limit",
      "detail": "Too many requests",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "internal",
      "detail": "An internal error occurred",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#internal"
    }
  ]
}

Authorizations

Authorization

string

header

required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.

Headers

x-idempotency-key

string<uuid>

required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Body

application/json

workspaceId

string<uuid>

required

The workspace the enrollment belongs to.

providerId

string<uuid>

required

providerConfigId

string<uuid>

required

program

enum<string>

required

The network program to enroll in. Ethoca, CDRN, and RDR are actionable pre-chargeback alert programmes. Ethoca and CDRN enroll by descriptors; RDR enrolls by bins/caids. VerifiINFORM is Visa's account-level fraud-reporting feed (covering TC40, TC15, and future Verifi INFORM feeds) — it requires externalReference instead of descriptors, and a merchant enrolls once to receive all Verifi INFORM alert types. SAFE (Mastercard fraud feed) is implicit on any Ethoca-enrolled merchant; enroll it explicitly only for a fraud-report-only merchant with a dedicated SAFE merchant reference — like VerifiINFORM, it requires externalReference instead of descriptors.

Available options:

Ethoca,

CDRN,

RDR,

VerifiINFORM,

SAFE

descriptors

string[]

The merchant descriptors to enroll for alerts. Required for Ethoca and CDRN. RDR enrolls by bins/caids instead of descriptors. Must be empty or omitted for account-level programs (VerifiINFORM, SAFE).

bins

string[]

RDR only. Card BINs to enroll, paired 1:1 with caids (bins[i] is confirmed against caids[i]). Required for RDR; omit for other programmes.

caids

string[]

RDR only. Card Acceptor IDs, paired 1:1 with bins. Required for RDR.

ruleset

string

Optional provider ruleset to apply.

externalReference

string

The provider merchant ID for an account-level program. Required for VerifiINFORM (the Verifi INFORM merchant ID) and SAFE (the dedicated SAFE merchant reference); Chargeblast uses this ID as the merchantId on the program's alert webhooks (TC40, TC15, SAFE, …), so it must be stored for ingestion to resolve incoming alerts. Omit for actionable programmes (Ethoca, CDRN, RDR) where the connector assigns the reference at enrol time.

Response

Enrollment created.

Last modified on October 9, 2026

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Enroll Descriptors for Dispute Alerts

Authorizations

Headers

Body

Response