Onboard Your End User

Onboarding an end user takes three steps: create an Organization for them, have them accept the Terms of Service, and approve the Organization.

1. Create an Organization

An Organization represents one of your end users: an individual or a business you move money for. Use the create Organization endpoint.

curl --request POST \
     --url https://api-staging.muralpay.com/api/organizations \
     --header "accept: application/json" \
     --header "authorization: Bearer $MURAL_API_KEY" \
     --header "content-type: application/json" \
     --data '
{
  "type": "business",
  "businessName": "Sun Tree Capital LLC",
  "email": "[email protected]"
}
'

The new Organization has tosStatus NOT_ACCEPTED and kycStatus inactive. Save the id from the response:

export ORGANIZATION_ID="<id from the response>"

2. Accept the Terms of Service

Your end user must accept the Mural Terms of Service before the Organization can be approved. Until then, endpoints that act for the Organization return a typed error.

Use the get Terms of Service link endpoint to get a hosted page where your end user reviews and accepts the terms.

curl --request GET \
     --url https://api-staging.muralpay.com/api/organizations/$ORGANIZATION_ID/tos-link \
     --header "accept: application/json" \
     --header "authorization: Bearer $MURAL_API_KEY"

Open the tosLink from the response and accept the terms. Then use the get Organization endpoint to confirm that tosStatus is ACCEPTED.

curl --request GET \
     --url https://api-staging.muralpay.com/api/organizations/$ORGANIZATION_ID \
     --header "accept: application/json" \
     --header "authorization: Bearer $MURAL_API_KEY"

tosStatus is one of:

• NOT_ACCEPTED: your end user has not accepted the Terms of Service. Send them the link from the get Terms of Service link endpoint.
• ACCEPTED: your end user accepted the Terms of Service.
• NEEDS_REVIEW: the Terms of Service changed. Your end user must accept the new terms.

3. Approve the Organization

An Organization needs an approved Compliance Review before it can hold funds or send payouts. In the sandbox, you can skip the real review and use the bypass endpoint instead.

Call the bypass Compliance Review endpoint for the Organization. It submits mock KYB / KYC data for the Organization through the standard Compliance Review flow.

curl --request POST \
     --url https://api-staging.muralpay.com/api/sandbox/simulate/complianceReview/$ORGANIZATION_ID \
     --header "accept: application/json" \
     --header "authorization: Bearer $MURAL_API_KEY"

Approval completes asynchronously, a couple of minutes later. kycStatus.type changes from inactive to pending, then to approved. Poll the get Organization endpoint until it is approved:

curl --request GET \
     --url https://api-staging.muralpay.com/api/organizations/$ORGANIZATION_ID \
     --header "accept: application/json" \
     --header "authorization: Bearer $MURAL_API_KEY"

When the Organization is approved, Mural creates an Account for it. You fund that Account in the next step.

The on-behalf-of header

Your API key belongs to your Parent Organization. To act for an end user's Organization, add the on-behalf-of header with its ID to endpoints that support it, such as the Accounts API and the Payouts API. The remaining steps use this header.