Customer preferences are the default accounts PCE uses when money has to move for a customer outside a normal transaction: an exception is received, funds must be recovered, a refund is issued, or a cash payment settles. You configure these once per customer, and PCE uses them to decide which account is debited or credited to settle that customer's activity.

Preferences are set on the customer, so they apply across that customer's accounts. Each preference is optional; configure only the ones your program uses.

Common use cases

• Point every ACH, check, or wire exception for a customer at a default Passport account so returns settle in one place.
• Name the external bank account a customer has authorized so PCE can recover an exception the Program Manager already covered.
• Choose the Passport account that receives a customer's ACH refunds.
• Choose the Passport account that receives a customer's cash (MoneyGram) settlement credits.

What you can configure

Each group maps to a field in the request. All are optional.

Set customer preferences

Send a POST to /v1/customer/{parentIdType}/{customerId}/preference, where parentIdType is id (the Passport-assigned reference) or externalId (your identifier). Each account you name is an existing Passport account or external account for that customer, referenced by its id or externalId.

Every request must carry the PromiseMode header: NEVER for a synchronous response, or ALWAYS for asynchronous processing.

Before you begin (all scenarios)

• The customer exists, and you have its id or externalId.
• The accounts you plan to name already exist for that customer: Passport accounts for exceptionAccount, refundAccount, and settlementAccount; an external account for recoveryAccount.

Scenario 1: Route a customer's exceptions to a default account

Name the Passport account that should absorb the customer's exceptions per rail, so ACH returns, returned check deposits, and wire exceptions all settle to accounts you chose in advance.

You'll also need: the Passport account id for each rail you want to cover.

Request

POST /v1/customer/id/4005450/preference
PromiseMode: NEVER

{
  "exceptionAccount": {
    "ach": { "id": "4005599" },
    "check": { "id": "4005599" },
    "wire": { "id": "4005599" }
  }
}

Scenario 2: Authorize an external recovery account

Name the external bank account the customer has authorized so PCE can recover an exception the Program Manager already covered from its own account. Recovery accounts are external accounts, referenced per rail.

You'll also need: the external account id for each rail you want to cover.

Request

POST /v1/customer/id/4005450/preference
PromiseMode: NEVER

{
  "recoveryAccount": {
    "ach": { "id": "4002155" },
    "check": { "id": "4002155" },
    "wire": { "id": "4002155" }
  }
}

Scenario 3: Set a default ACH refund account

Name the Passport account used to process the customer's ACH refunds.

You'll also need: the Passport account id for the refund account.

Request

POST /v1/customer/id/4005450/preference
PromiseMode: NEVER

{
  "refundAccount": {
    "ach": { "id": "4005599" }
  }
}

Scenario 4: Direct cash settlement to an account

Name the Passport account that receives credits for the customer's cash (MoneyGram) payments.

You'll also need: the Passport account id that should receive cash settlement.

Request

POST /v1/customer/id/4005450/preference
PromiseMode: NEVER

{
  "settlementAccount": {
    "moneygram": { "id": "4003826" }
  }
}

You can also send several groups in one request; PCE stores the full set you provide.

Response: 200 OK

A successful request returns 200 OK with no body. Retrieve the customer's preferences to confirm what's stored.

Retrieve customer preferences

Send a GET to /v1/customer/{parentIdType}/{customerId}/preference with the PromiseMode header to read the configured preferences. Each configured entry resolves to the full account resource, including its resourceName (account for Passport accounts, externalAccount for recovery accounts), url, and id.

Request

GET /v1/customer/id/4005450/preference
PromiseMode: NEVER

Response: 200 OK

{
  "exceptionAccount": {
    "ach": {
      "resourceName": "account",
      "url": "/v1/customer/id/4005450/account/id/4003834",
      "id": 4003834
    },
    "check": {
      "resourceName": "account",
      "url": "/v1/customer/id/4005450/account/id/4003834",
      "id": 4003834
    },
    "wire": {
      "resourceName": "account",
      "url": "/v1/customer/id/4005450/account/id/4003834",
      "id": 4003834
    }
  },
  "recoveryAccount": {
    "ach": {
      "resourceName": "externalAccount",
      "url": "/v1/customer/id/4005450/externalAccount/id/4002155",
      "id": 4002155
    }
  },
  "refundAccount": {
    "ach": {
      "resourceName": "account",
      "url": "/v1/customer/id/4005450/account/id/4003834",
      "id": 4003834
    }
  },
  "settlementAccount": {
    "moneygram": {
      "resourceName": "account",
      "url": "/v1/customer/id/4005450/account/id/4003834",
      "id": 4003834
    }
  }
}

Request reference

The complete set of fields for the preference request. Every group and rail is optional; send only what you want in effect.

Header and path

exceptionAccount

Passport accounts that process the customer's exceptions, per rail.

recoveryAccount

External accounts authorized to recover exceptions the Program Manager processed earlier, per rail.

refundAccount

Passport account used to process the customer's refunds.

settlementAccount

Passport account that receives the customer's cash settlement credits.

Account reference object

Every rail above points to an account with one of these identifiers.

Best practices

See also

• Exceptions & reconciliation: review and resolve the inbound credits and debits these preferences help settle
• Accounts: the customer and Passport accounts these preferences point to
• Getting Started: authentication, PromiseMode, webhooks, and shared setup