Payees can be saved as Contacts to simplify and accelerate repeat transactions. Once added, these contacts can be reused across multiple payment flows without re-entering details.

Contacts are intended for storing third-party payee details only. To add and manage your own external bank accounts, add External Accounts.

Contacts can represent:

Internal users within the platform (via PPI)
External entities such as bank accounts, cards, or addresses

This allows you to create a unified payee repository for initiating payments across multiple rails.

Common Use Cases:

Save frequently used payees for quick payment initiation
Add internal users via PPI for seamless intra-platform transfers
Store external bank account details for ACH/WIRE payments
Configure card or virtual card recipients
Maintain payee details for recurring or bulk payouts

How it Works

Contacts act as reusable payment details of any third-party, enabling transactions to be initiated using stored and validated payee details instead of manual input.

Contacts act as pre-configured payment endpoints
Transactions reference contact details instead of raw input data
Using contacts:
- Reduces input errors
- Improves transaction speed
- Enables better reconciliation
PPI-based contacts bypass external validation flows

Add Contacts

Use the POST /v1/customer/id/{id}/contact (or using externalId) API to create a reusable payee record for a third party.

A contact can store one or more payout destinations, depending on how you plan to pay that recipient.

Key Details Required:

Parameter	Required	Description
`name`	✓	Display name of the contact
`contactType`	✓	Type of contact: `INDIVIDUAL` `BUSINESS`
`ppi`	Conditional	Passport Payment ID for internal contacts. Use the POST `v1/ppi/verify` endpoint to verify the PPI you are adding as contact.
`firstName`	Conditional	Required if `contactType = INDIVIDUAL`
`lastName`	Conditional	Required if `contactType = INDIVIDUAL`
`legalName`	Conditional	Required if `contactType = BUSINESS`
`email`	Conditional	Required for Virtual Card payments

Contacts can be configured based on the payment method:

External Bank Account (ACH / Wire - Domestic)

Use externalAccount when you want to save a third-party domestic bank account as a reusable payout destination.

An external bank account contact can later be used as the destination for following transactions:

This makes it useful for vendor payments, supplier disbursements, payroll transfers, and any payout flow where funds need to be sent to another person’s or business’s bank account outside the system.

Parameter	Required	Description
`externalAccount.accountNumber`	✓	Bank account number
`externalAccount.routingNumber`	✓	ACH routing number
`externalAccount.wireRoutingNumber`	Optional	Wire routing number
`externalAccount.type`	✓	`SAVINGS` or `CHECKING`
`externalAccount.holderType`	✓	`CONSUMER` or `CORPORATE`

Mailing Address (Check Payments)

Use mailingAddress when you want to save a physical mailing destination for check payouts.

A mailing address contact can later be used as the destination for Pay via Check transactions, which makes it useful for vendor payments, mailed disbursements, and any payout flow that requires a physical check.

Parameter	Required	Description
`mailingAddress.addressLine1`	✓	Primary street address for the mailing destination
`mailingAddress.addressLine2`	Optional	Secondary address details such as apartment, suite, or unit
`mailingAddress.city`	✓	City of the mailing destination
`mailingAddress.state`	✓	Two-character state code
`mailingAddress.zip`	✓	ZIP or postal code
`mailingAddress.name`	✓	Name of the recipient or payee
`mailingAddress.phone`	Optional	Contact phone number for the mailing address
`mailingAddress.isPrimary`	Optional	Indicates if this is the primary mailing address for the contact
`mailingAddress.usage.isPayorAddress`	Optional	Indicates if this address should be treated as a payor address
`mailingAddress.isDefault`	Optional	Indicates if this is the default mailing address

Virtual Card (Virtual Card Issuance Details)

Use email when you want to configure a recipient's email for sharing a virtual card's details once issued by your program.

This is useful a virtual card generated within the system. The email address is used to send the virtual card details to the recipient.

Parameter	Required	Description
`email`	✓ (PCE issued Virtual Cards)	Email to send card details of a Virtual Card issued via Priority's PCE.

International Account (International Wire)

Use internationalExternalAccount when you want to save a third-party international bank account as a reusable payout destination.

An international external account contact can later be used as the destination for international wire payouts. This is useful for sending funds to recipients outside the United States when the payout requires SWIFT details, supported currencies, or country-specific routing information.

Parameter	Required	Description
`internationalExternalAccount.accountNumber`	✓	Account number
`internationalExternalAccount.swiftCode`	✓	SWIFT code
`internationalExternalAccount.country`	✓	Country
`internationalExternalAccount.acceptedCurrency`	✓	Currency supported

Validations can be triggered during contact creation, depending on the payment method and the details provided.

After submitting the request, the system checks that all required information is present. If any validation fails, the request is rejected immediately, and an error response is returned. You must correct the issue and resubmit the request. For a complete list of validation errors and how to resolve them, refer to the HTTP Response Codes.

Key System Validations:

Contact type must be valid (INDIVIDUAL or BUSINESS)
Required fields must be provided based on payment method
PPI should be verified before adding internal contacts
External account details may undergo OFAC validation or Account verification (EWS)

NOTE:

PO Box addresses are not allowed for contact addresses.

Validation rules vary by payment method

Some features (e.g., MONEYGRAM) depend on program-level configuration

Retrieve Contact Details

On successful creation, a unique id is assigned to the contact and this unique contact id can be used for initiating transactions.

Use the GET v1/customer/id/{id}/contact/id/{id} API to view the important information such as the contact's status and verification details are returned in the response. These identifiers are required for:

Fetching contact details
Initiating payments
Updating or deleting contacts

Key information:

External accounts undergo validation and enrichment
Verification status is maintained for:
- OFAC screening
- Account validation (EWS)
Contact details can be updated post creation (subject to validation rules)

Contact Statuses

Status	Description	Reason
ACTIVE	Contact is available for use	Successfully created
INACTIVE	Contact is not usable	Disabled or restricted
PENDING_VERIFICATION	Awaiting validation	External account checks in progress
FAILED	Contact creation failed	Validation or compliance failure

Best Practices

Practice	Description
Verify PPI before adding	Ensures internal contacts are valid.
Use accurate bank details	Prevents transaction failures. Do not use Contacts to store your own bank account details; use External Accounts instead
Reuse contacts for repeat payments	Improves efficiency and reduces errors
Store contact identifiers	Required for downstream transactions
Avoid PO Box addresses	Not supported for contact creation