Manage applications with the API
Intelligent boarding is in beta. To opt in, reach out to your Payabli contact.
An application is a paypoint’s request for service. It boards a business through one of its paypoints, and moves through review until its requested services are live. Use the applications API to create an application, submit it for review, respond to underwriting, and track its status. For how applications fit into the wider model, see the boarding overview.
Considerations
- The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
- An application boards a business that already has a paypoint. Create the business and its paypoint first.
- You can update an application only while it’s in
draft. After you submit it, Payabli’s review moves it from one status to the next. See Boarding application statuses for every status and what moves an application between them. - Application responses and lifecycle action responses include an
allowedActionsarray. Check it for the action you want before you call a lifecycle endpoint. The array can also list actions that only Payabli performs.
Create an application
Send a POST request to /v2/requests with the businessReference of the business to board and a requestTemplate with the reference of your organization’s boarding template. Payabli assigns the application’s underwriting policy from the template, so a submitted application without one fails in review. Optionally, send a paypointReference to board a specific paypoint and an externalId from your own system. New applications start in draft. See the API reference for this endpoint for full documentation.
The response returns the new application’s reference, status, and allowed actions:
The requestsReference in the response is the reference you use to read and manage the application.
To request services, add a services object that lists the Pay In services under moneyIn and the Pay Out services under moneyOut. See the API reference for the accepted values.
The response returns the requested services on the application:
Get an application
Send a GET request to /v2/requests/{requestsReference}. See the API reference for this endpoint for full documentation.
The response returns the application’s full detail, including its current status and allowed actions:
List applications
Send a GET request to /v2/requests. Page the results with the page and limit query parameters. Pages start at 1, and each page holds 20 applications unless you set limit. See the API reference for this endpoint for full documentation.
The response returns a page of applications with pagination metadata:
Update an application
Send a PATCH request to /v2/requests/{requestsReference} with only the fields you want to change. The application must be in draft. See the API reference for this endpoint for full documentation.
The response returns the updated application:
To change the requested services, send the full services object. It replaces the current services, so include every service you want to keep. Leave services out of the request to keep the current services.
Validate an application
Before you submit, check that the business, its people, and its payment methods have everything the requested services need. Send a POST request to /v2/requests/{requestsReference}/validate. Validation doesn’t change the application. See the API reference for this endpoint for full documentation.
When valid is true, the records have everything the requested services need. When valid is false, each section lists its missingFields. The field value is the path on the record to fix, such as business.taxReference:
Fix the record that holds the field, such as with a PATCH request to the business, then validate again.
What validation checks
Validation is stricter than the create endpoints, so a record can save without a field that validation still reports as missing. Request services on the application before you validate, because many requirements depend on them. If the application requests no services, validation checks the requirements for every service.
Validation reports any of these requirements that the records don’t meet, whether a field is missing or its value isn’t valid:
- Business:
legalStructure,description,taxReference,establishedDate,merchantCatCode,incorporationState,taxIdCountry,isForeignOwned, at least one address with a street line, and at least one item each inphone,emails, andoperatingSeasons. SendisForeignOwnedastrueorfalse, even when the business isn’t foreign-owned. IfprocessingMetrics.inboundOnlinePercentis more than 0, the business also needs awebsite. IfisTaxExemptistrue, it needstaxExemptClassification. - Pay In volumes: when the application requests Pay In services,
processingMetrics.numberOfTransactions, the three receivables volumes, and the sales channel percentages.monthlyReceivablesVolumemust be more thanlargestReceivableSize, which must be more thanaverageReceivableSize. At least one ofinboundPresentPercent,inboundOnlinePercent, andinboundMotoPercentmust be more than 0, and together they must add up to 100. When the application requestsCard, or whenadvancedDeliveryistrue, the business also needsadvancedDeliveryDays. WhenadvancedDeliveryistrue, it also needspercentAdvancedDelivery. - Pay Out volumes: when the application requests Pay Out services,
payoutMetrics.numberOfTransactions,monthlyPayablesVolume, andlargestPayablesSize.monthlyPayablesVolumemust be more thanlargestPayablesSize. - People: every person needs a phone number and an email. Every person except an
Employeealso needstitle,dateOfBirth,nationality, and an address. People with US nationality needssn. Everyone else needsnationalIdNumberinstead. - Ownership: at least one person marked
isPrimaryController, exactly one owner markedisSigner, and total ownership of 100% or less. Unless the legal structure isgovernmentornon-profit, every owner needsownershipPercentage, and at least one owner must have 25% or more. - Payment methods: when the application requests any service, at least one payment method, with exactly one marked as the default. Each bank account needs
nickname,financialInstitution, and at least oneusagevalue. Between them, the accounts needdepositsand eitherbillingorrefunds. Card services allow at most onedepositsaccount. Check payouts need an account withpayOutFundingorreturns. - Documents: every required document in the application’s document requirements, with at least one file uploaded. A business with an
annualRevenueof $1,000,000 or more needs bank statements.
Upload documents
An application can ask for documents, such as bank statements or a signed W-9. The requirements come from the application’s template and from Payabli business rules. For example, a business with an annualRevenue of $1,000,000 or more needs bank statements. Upload the documents through the API before you submit, or when underwriting requests them.
List the requirements
Send a GET request to /v2/requests/{requestsReference}/documents/requirements. See the API reference for this endpoint for full documentation.
Each requirement gives the fieldPath and subjectTypes to upload with, the allowedFormats, the maxUploads it takes, and its uploadedCount. A person requirement appears once for each owner of the business, with that owner’s personReference. When required is true, validation reports the requirement as missing until a document is uploaded:
Upload a document
Send a POST request to /v2/requests/{requestsReference}/documents as multipart form data, with one file and these fields:
fieldPath: the requirement’sfieldPath.subject: one of the requirement’ssubjectTypes:business,paypoint, orperson.personReference: for a person requirement, thepersonReferencefrom the requirement.
The file can be up to 10 MB, in one of the requirement’s allowedFormats. Payabli checks the file’s content, not only its name. See the API reference for this endpoint for full documentation.
The response returns the document, with the documentReference you use to delete it:
If the upload doesn’t fit a requirement, the request fails with 400 and the error VALIDATION_ERROR, and the message says why. For example, fieldPath and personReference don’t match a requirement, the file is empty, too large, or in a format the requirement doesn’t accept, or the requirement already has maxUploads documents. Uploading doesn’t change the application’s status.
List and delete documents
To see what’s uploaded, send a GET request to /v2/requests/{requestsReference}/documents. See the API reference for this endpoint for full documentation.
To remove a document, such as to replace it, send a DELETE request to /v2/requests/{requestsReference}/documents/{documentReference}. A deleted document no longer counts toward its requirement’s maxUploads. See the API reference for this endpoint for full documentation.
Submit an application
When the business, its people, payment methods, and services are in place, send a POST request to /v2/requests/{requestsReference}/submit. The application must be in draft and have a signer. The signer is the owner flagged with isSigner on their business link. To choose the signer on this call instead, send their personReference in signer. Payabli records the signer’s identity from their person record and business link, so update those with the people endpoints before you submit. Include a signer with the signature details. To record the IP address of the signer’s device as your system saw it, include reportedSignerIp in signer. Payabli stores it separately from the IP address it observes on the request. See the API reference for this endpoint for every signature option, including drawn signatures and signatures from your own e-sign tool.
The response returns the application’s new status and allowed actions:
If the application has no signer, the request fails with 422 and the error SIGNER_REQUIRED. Set isSigner on one of the business’s owners, or send signer.personReference, then submit again. If signer.personReference names a person who isn’t an owner, the request fails with 422 and the error SIGNER_NOT_OWNER.
Submit doesn’t check every rule that validation reports, such as the primary controller and ownership rules. Validate the application and resolve its missing fields before you submit.
After you submit the application, verification starts automatically. The application then either approves automatically or goes to underwriting for review. If processing fails, the application moves to error, and Payabli can recover it to the status it had before the error.
Respond to underwriting requests
During review, underwriting can request documents or ask a question. The application waits in pendingdocuments or pendingresponse until you mark the request as answered, and then returns to review. Neither endpoint takes a request body. When underwriting requests documents, upload them first, then mark them as provided.
When the application is in pendingdocuments, mark the documents as provided with a POST request to /v2/requests/{requestsReference}/provide-documents. See the API reference for this endpoint for full documentation.
When the application is in pendingresponse, mark the information as provided with a POST request to /v2/requests/{requestsReference}/provide-response. See the API reference for this endpoint for full documentation.
Both endpoints return the application to pendingreview:
Withdraw an application
Send a POST request to /v2/requests/{requestsReference}/withdraw, with an optional reason that’s recorded in the status history. You can withdraw an application in draft, submitted, pendingdocuments, or pendingresponse. You can’t reopen a withdrawn application. See the API reference for this endpoint for full documentation.
The response returns the application’s new status. A withdrawn application has no allowed actions:
Track status changes
To see how an application reached its current status, send a GET request to /v2/requests/{requestsReference}/history. See the API reference for this endpoint for full documentation.
The response lists every transition, oldest first, with what triggered each change and any reason recorded with it:
History records changes only. An approved application that fails enablement the same way on every attempt doesn’t add new entries, so check enablement to follow it.
Check enablement after approval
After an application is approved, Payabli sets up each requested service with its processor. This is called enablement. The application stays approved or autoapproved while enablement runs, and it moves to activated after every service is set up. To see why an approved merchant isn’t live yet, send a GET request to /v2/requests/{requestsReference}/enablement. Enablement doesn’t send webhooks, so poll this endpoint to follow it. See the API reference for this endpoint for full documentation.
The response shows the overall state, the state of each service, and blockedOn, which says why enablement isn’t moving. In this example, Payabli is waiting on a processor and retries automatically:
When blockedOn is merchant_data, the merchant’s data needs a correction before enablement can continue. Each service’s missingFields lists the fields the processor refused or reported as missing, and its message explains what’s needed.
Related resources
See these related resources to help you get the most out of Payabli.
References
- Required fields for boarding applications - Learn more about the Know Your Customer (KYC) and Know Your Business (KYB) fields required for merchant boarding