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 add an external bank account, of a third-party within the system.

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)

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)

Parameter	Required	Description
`mailingAddress.addressLine1`	✓	Address line 1
`mailingAddress.city`	✓	City
`mailingAddress.state`	✓	State
`mailingAddress.zip`	✓	ZIP code
`mailingAddress.name`	✓	Recipient name

Card (Card / Virtual Card Payments)

Parameter	Required	Description
`card.cardNumber`	✓	Card number
`card.expiryMonth`	✓	Expiry month (MM)
`card.expiryYear`	✓	Expiry year (YYYY)
`card.cvv`	✓	CVV
`card.brand`	✓	`VISA`, `MASTERCARD`, `DISCOVER`
`email`	✓ (PCE issued Virtual Cards)	Email to send card details of a Virtual Card issued via Priority's PCE.

International Account (International Wire)

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

Validations can be triggered either during contact creation.

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)

Transaction 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