Create a payment profile

post

https://test-api.payology.io/api/v1/payment-profile

Create an ACH or CC profile. X9 does not use payment profiles. Replace the CC account placeholder with an approved processor test card before execution. HTTP 201 can include a declined verification result; inspect response_code, active and payment_profile_result.

Result codes in the response examples

HTTP status and result code are operation-specific. Field-validation messages can include the affected field name.

HTTP	Code	Result	Meaning
201	R0000	Ok	The request was processed successfully
201	R0006	Error	The routing number is invalid
400	R0002	Error	Field is not properly formatted
400	R0118	Error	Reference_id already exists
400	R0141	Error	Customer token is inactive
400	R0142	Error	Customer token is invalid
401	R0003	Error	Authentication token is invalid
403	R0003	Error	Access not allowed
404	R0142	Error	Customer token is invalid
500	R0999	Error	Something went wrong

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

JSON request body. Required and conditional fields are defined by the schema. Named examples show supported request variants.

ACHProfile Request. Field definitions, required properties and payload examples describe its use in the operations below.

customer_token

string

required

[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}

Customer UUID returned by customer creation or lookup.

default

boolean

Whether this is the customer default payment profile.

account_type

string

enum

required

Type of bank account, using the exact allowed enum value.

Allowed:

name_on_account

string

required

length between 1 and 50

^[a-zA-Z0-9.,'&\-\s]*$

Account-holder name. Required for an ordinary non-mobile X9 submission.

routing_number

string

required

length between 8 and 9

^[0-9]{8,9}$

Bank routing number; send as a string to preserve leading zeroes.

account_number

string

required

length between 5 and 17

^[0-9]+$

Bank or card account number. Request fields contain the supplied account; response fields are masked.

verify_validity

boolean

Whether to request the additional bank/card verification flow. A failed verification can be represented inside a created-profile response.

reference_id

string

required

length between 1 and 50

Partner-assigned reference used for reconciliation and supported reference lookups. Resource creation can enforce uniqueness within its scope.

source

ACH Payment Source.virtual Terminal | ACH Payment Source.api | ACH Payment Source.portal

Origin recorded for the resource, using the documented API/Portal/mobile source vocabulary.

device_version

string

length ≤ 15

Originating device version.

string

enum

Originating device operating system, using the documented enum spelling.

Allowed:

os_version

string

length ≤ 15

Originating operating-system version.

device

string

length ≤ 20

Originating device name/model.

reference_id_2

string

length ≤ 50

Optional second partner-assigned reference.

team_member_id

string

length ≤ 50

Optional partner team-member reference.

customer_ip

string

Originating customer IP address, when supplied by the integration.

bypass_webhook

boolean

When true, suppress the webhook associated with this operation where supported. This does not change the payment processing outcome.

sdk_version

string

length ≤ 50

Version of the submitting integration SDK.

metadata

string

Optional integration metadata stored as a string. If storing JSON, send serialized JSON text rather than a nested JSON object.

type

string

enum

required

Payment-method selector. Use X9 for payments and ACH/CC for profiles as specified on the operation.

Allowed:

Responses

default

Other infrastructure or forwarded downstream response. HTTP status and body must be preserved; do not assume every error has a Payology R-code. No fixed payload is guaranteed.

201Profile creation completed; inspect the business outcome as well as HTTP status.

400Invalid fields, selector, or business rule. Consult the individual example code.

401Authentication failed. Some services also use 401 for organization access denial. Gateway bodies can differ.

403Permission or organization access denied; the gateway can reject the request before it reaches the service.

404Requested resource or lookup reference was not found.

413Proxy JSON body exceeds the configured 1 MiB limit; base64 images count toward that limit.

429Gateway throttling or quota. Exact quota, retry headers and deployed body were not verified. This is a platform possibility, not an observed Payology response.

500Unhandled service failure. Gateway configuration/authorizer failures can also return 500.

502Proxy could not obtain an HTTP response from the selected payment service.

504Gateway integration timeout or failure. The service may still have committed a create request. This is a platform possibility, not an observed Payology response.