# Weavr Embedded Payment Run API Weavr Payment Run Plug-in API provides a simple and flexible way for Embedders to add payment execution capabilities in their application. By integrating Weavr Payment Run plug-in API in your application, you can embed banking and payment capabilities within your app to boost productivity for your users in a seamless experience. # Authentication Each request to the API must include an `api_key` that represents your account. You can obtain an API Key by registering for a Embedder account [here](https://portal.weavr.io/register/?plugin=payment-run). Almost all endpoints require a secondary authentication token `auth_token` that represents the user for whom the request is being executed. # Postman Collection To help you get started with your integration, you can download the [Postman](https://postman.com) collection [here](https://sandbox.weavr.io/payment-run/v1/postman). The collection includes the steps you’ll need to follow to integrate Embedded Payment Run within your app. The collection makes use of environment variables to pre-fill details associated with your Sandbox account, such as your account’s API Key. You can download your Sandbox Account environment file from the [Sandbox Portal](https://portal.weavr.io/register/?plugin=payment-run). Version: v1 License: private ## Servers Sandbox ``` https://sandbox.weavr.io/payment-run ``` ## Security ### apiKey The API Key representing your Weavr account. You can find your API Key in your Weavr Portal in the API Credentials page. Type: apiKey In: header Name: api-key ### authToken The authentication token representing the user. This will be included in the login response object. Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Weavr Embedded Payment Run API](https://api.weavr.io/_bundle/products/payment-run/openapi.yaml) ## Tokens ### Acquire auth token - [POST /v1/login_with_password](https://api.weavr.io/products/payment-run/openapi/tokens/acquireauthtoken.md): Authenticate a user with the email and password that they provided when registering. Given that the user credentials are correct, this returns a token that can then be used to authorise other secured operations. In case the password is expired, a temporary token is returned, which can be used solely for updating the password. The token returned is valid for 5 minutes from last activity. ### Logout - [POST /v1/logout](https://api.weavr.io/products/payment-run/openapi/tokens/logout.md): Logs out the user and terminates the session identified by the auth_token in the Authorization Header. ## Passwords ### Create a password - [POST /v1/password/{user_id}](https://api.weavr.io/products/payment-run/openapi/passwords/passwordcreate.md): Create a new password for the user identified by the user_id path parameter. ### Update a password - [POST /v1/passwords/update](https://api.weavr.io/products/payment-run/openapi/passwords/passwordupdate.md): Update the password for the logged-in user. ### Validate a password - [POST /v1/passwords/validate](https://api.weavr.io/products/payment-run/openapi/passwords/passwordvalidate.md): Check that a password adheres to all complexity checks. ### Initiate lost password process - [POST /v1/passwords/lost_password/start](https://api.weavr.io/products/payment-run/openapi/passwords/lostpasswordinitiate.md): Initiate the lost password process. If the email address provided is associated with an active user, an email will be sent, containing a URL that redirects the user to change their password. The URL contains request parameters for all of the parameters required to change the password for the user via the /passwords/lost_password/resume POST endpoint. ### Resume lost password process - [POST /v1/passwords/lost_password/resume](https://api.weavr.io/products/payment-run/openapi/passwords/lostpasswordresume.md): This is the second and final step in updating the password of a user who forgot their password. ## Additional Factors ### Enrol a user device for authentication using one-time passwords - [POST /v1/authentication_factors/otp/{channel}](https://api.weavr.io/products/payment-run/openapi/additional-factors/enroldeviceusingotpstepone.md): This is the first step in enrolling the logged-in user's mobile device, where a one-time password is sent to the device. _Note that on the Sandbox Environment, text messages are not sent and the one-time-password is always \"123456\"._ ### Verify enrolment of a user device for authentication using one-time passwords - [POST /v1/authentication_factors/otp/{channel}/verify](https://api.weavr.io/products/payment-run/openapi/additional-factors/enroldeviceusingotpsteptwo.md): The second step in enrolling the logged-in user (root or authorised user) to use one-time-passwords to enable verification of transactions. _Note that on the Sandbox Environment, text messages are not sent and the verificationCode is always set to \"123456\"._ ## Step up ### Issue a one-time password that can be used to step-up a token - [POST /v1/stepup/challenges/otp/{channel}](https://api.weavr.io/products/payment-run/openapi/step-up/stepupscachallenge.md): Initiates the step-up token process by sending an SMS with an one-time-password to a device belonging to the logged-in user that was previously enrolled through /authentication_factors/otp/{channel} endpoint. This process is required for endpoints that require a step-up token to complete the call. _Note that on the Sandbox Environment, text messages are not sent and the one-time-password is always \"123456\"._ ### Verify a step-up token using a one-time password - [POST /v1/stepup/challenges/otp/{channel}/verify](https://api.weavr.io/products/payment-run/openapi/step-up/stepupscaverify.md): Completes the verification process for a step up token. _Note that on the Sandbox Environment, text messages are not sent and the verificationCode is always \"123456\"._ ## Buyers Buyers are identities representing a business Once on-boarded, Buyers can create payment runs and pay their suppliers in your application. ### Create a buyer - [POST /v1/buyers](https://api.weavr.io/products/payment-run/openapi/buyers/buyercreate.md): Buyers are identities representing a business. Once on-boarded, Buyers can create and manage their own instruments via your plugin. The information provided must be accurate and will be passed on for KYB verification with our partner. ### Get buyer details - [GET /v1/buyers](https://api.weavr.io/products/payment-run/openapi/buyers/buyerget.md): Retrieve the details of the buyer that the logged-in user belongs to. Required user role: ADMIN ### Update a buyer - [PATCH /v1/buyers](https://api.weavr.io/products/payment-run/openapi/buyers/buyerupdate.md): Update the buyer currencies and admin roles. Required user role: ADMIN ### Start admin user email verification - [POST /v1/buyers/verification/email/send](https://api.weavr.io/products/payment-run/openapi/buyers/buyeradminuseremailverificationcodesend.md): The first step in verifying a admin user's email. The admin user whose email address is to be verified is sent an email containing a randomly generated code. This code must then be provided in the _buyerAdminUserEmailVerify_ operation to verify the admin user's email address. _Note that on the Sandbox Environment, the verificationCode is always set to \"123456\"._ ### Verify admin user email - [POST /v1/buyers/verification/email/verify](https://api.weavr.io/products/payment-run/openapi/buyers/buyeradminuseremailverify.md): The second step in verifying the admin user's email. The randomly generated code sent to the admin user via email, using the _buyerAdminUserEmailVerificationCodeSend_ operation, is submitted here to verify the admin user's email. This is needed as part of the verification process for basic due diligence. _Note that on the Sandbox Environment, the verificationCode is always set to \"123456\"._ ### Start buyer KYB - [POST /v1/buyers/kyb](https://api.weavr.io/products/payment-run/openapi/buyers/buyerkybstart.md): Buyers need to complete due diligence (KYB) before they can create payment runs and pay their suppliers. This operation initiates the due diligence process for the buyer that the logged-in user belongs to. Due Diligence is handled by a KYB provider - you will need to embed the KYB UI Component in your application so that the buyer will be able to perform the KYB process. To initialise the KYB UI Component, you need a reference that is given you in the response of this operation. Required user role: ADMIN ### Get buyer KYB status - [GET /v1/buyers/kyb](https://api.weavr.io/products/payment-run/openapi/buyers/buyerkybget.md): Returns the KYB status for the buyer that the logged-in user belongs to. Required user role: ADMIN ### Update Buyer's KYB details - [PATCH /v1/buyers/kyb](https://api.weavr.io/products/payment-run/openapi/buyers/buyerupdatekyb.md): Update the details of the buyer that the logged-in user belongs to. The following Buyer details are verified during due diligence (KYB) and cannot be updated via the API once the Buyer has been verified: - Admin User Name - Admin User Surname - Admin User Email - Admin User Mobile Country Code - Admin User Mobile Number - Admin Date of Birth - Company Business Address If these details need to be changed after due diligence is completed, please contact Customer Support to restart the Due Diligence process. Required user role: ADMIN ## Buyer Authorised Users Buyers can invite authorised users to access their account. Once on-boarded, authorised users can transact on behalf of the identity they are on-boarded with. Authorised users are typically employees who have access to company's banking accounts. Note that `/users` endpoints are to be used only for performing operations related to authorised users - getting or updating the details of _admin_ users is to be done via `/buyers` endpoints. ### Create a user - [POST /v1/users](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/usercreate.md): Creates a user that belongs to the buyer that the logged-in user belongs to. To Create an Authorised User you would need a stepped-up token. After calling this endpoint you need to step-up ( issue a challenge /stepup/challenges/otp/{channel} ). More details on how to step-up a token can be found here Step-Up. Once on-boarded, users have access and manage the buyer's payment runs. Users are assigned roles which limit the level of access they have and what they can do on behalf of the buyer. Required user role: ADMIN ### Get all users - [GET /v1/users](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/usersget.md): Fetches all authorised users associated with the buyer that the logged-in user belongs to. Required user role: ADMIN ### Get a user - [GET /v1/users/{user_id}](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/usergetbyid.md): Retrieves the user identified by the user_id path parameter. Required user role: ADMIN ### Update a user - [PATCH /v1/users/{user_id}](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/userupdate.md): Update the details of a user identified by the user_id in the the path parameter. After calling this endpoint you need to step-up ( issue a challenge /stepup/challenges/otp/{channel} ). More details on how to step-up a token can be found here Step-Up.. Only the fields that are specified in the request body will be updated. All other fields will remain unchanged. When patching a mobile number, the new mobile number should be enrolled for Additional Factors. Required user role: ADMIN ### Activate a user - [POST /v1/users/{user_id}/activate](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/useractivate.md): Activate the user identified by the user_id path parameter. By default, any new users created will be automatically activated. This operation needs to be used only if the user was previously de-activated using the _userDeactivate_ operation, or if the user was de-activated automatically after multiple incorrect login attempts. Required user role: ADMIN ### Deactivate a user - [POST /v1/users/{user_id}/deactivate](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/userdeactivate.md): De-activate the user identified by the user_id path parameter. Deactivated users cannot log in or execute any operations with their credentials. This operations is not final and a user can be re-activated using the userActivate operation. Note that another active user would need to log in so as to re-activate the de-activated user. Required user role: ADMIN ### Send a user invite - [POST /v1/users/{user_id}/invite](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/userinvitesend.md): Once a user is created using the _userCreate_ operation, the user needs to setup his/her password. An invitation needs to be sent to the user in order to be able to set up the password for the first time. The invitation email, which remains valid for 1 month, will contain a URL having all information required to setup the password via the _userInviteConsume_. Required user role: ADMIN ### Validate a user invite - [POST /v1/users/{user_id}/invite/validate](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/userinvitevalidate.md): Check if a user's invite is still valid. This operation is useful to avoid having the user fill in a form only to be held by a validation issue (eg. expired invite). ### Consume a user invite - [POST /v1/users/{user_id}/invite/consume](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/userinviteconsume.md): Consumes an invitation previously sent to the user via _userInviteSend_. This is needed so that the invited user sets up the password. _Note that on the Sandbox Environment, the inviteCode is always set to \"123456\"._ ### Send an email verification code to the authorised user - [POST /v1/users/verification/email/send](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/authoriseduseremailverificationcodesend.md): The first step in verifying an authorised user's email. The authorised user whose email address is to be verified is sent an email containing a randomly generated code. This code must then be provided in the _authorisedUserEmailVerify_ operation to verify the authorised user's email address. _Note that on the Sandbox Environment, the verificationCode is always set to \"123456\"._ ### Verify email of the authorised user - [POST /v1/users/verification/email/verify](https://api.weavr.io/products/payment-run/openapi/buyer-authorised-users/authoriseduseremailverify.md): The second step in verifying the authorised user's email. The randomly generated code sent to the authorised user via email, using the _authorisedUserEmailVerificationCodeSend_ operation, is submitted here to verify the authorised user's email. This is needed as part of the verification process for basic due diligence. _Note that on the Sandbox Environment, the verificationCode is always set to \"123456\"._ ## Payment runs A Payment run contains a list of supplier payments. A Payment run can be - created by a user with a `CREATOR` role - confirmed by a user with a `CONTROLLER` role - funded by a user with a `CONTROLLER` role Note that the Controller user must have their mobile device enrolled to SCA. Before a payment run can be executed, it must be funded. Users with the `CONTROLLER` role must link their company's bank account(s) that are represented as Linked Accounts, which than can be used as the funding source for a payment run. Depending on the bank's constraints it may not be possible to deposit the total amount of funds required for a payment run, in which case the payment run will be automatically split into funding groups. All funding groups must be funded and executed for the payment run to be marked as completed. Note that even if the payment is created successfully, you still need to check its status in order to determine if it is `completed` or`failed`. ### Create a payment run - [POST /v1/payment_runs](https://api.weavr.io/products/payment-run/openapi/payment-runs/postpaymentrun.md): Create a new payment run containing a list of outstanding supplier payments. Note that all the supplier payments in a payment run is limited to one currency. The currency of the payment run are enabled upon the Buyer’s registration. Required user role: CREATOR ### Get payment runs - [GET /v1/payment_runs](https://api.weavr.io/products/payment-run/openapi/payment-runs/getpaymentruns.md): Retrieve the list of payment runs belonging to the buyer that the logged-in user belongs to. Required user roles: CONTROLLER OR CREATOR ### Get a payment run - [GET /v1/payment_runs/{payment_run_id}](https://api.weavr.io/products/payment-run/openapi/payment-runs/getpaymentrunsid.md): Retrieve a payment run belonging to the buyer that the logged-in user belongs to. Required user roles: CONTROLLER OR CREATOR ### Update a payment - [PUT /v1/payment_runs/{payment_run_id}](https://api.weavr.io/products/payment-run/openapi/payment-runs/putpaymentrunsid.md): Update the details of a payment identified by the paymentId that is in the PENDING_CONFIRMATION state. Required user role: CREATOR ### Confirm a payment run - [POST /v1/payment_runs/{payment_run_id}/confirm](https://api.weavr.io/products/payment-run/openapi/payment-runs/postpaymentrunsidconfirm.md): Confirm that a payment run can be executed. Required user role: CONTROLLER ### Get a payment run funding instructions - [GET /v1/payment_runs/{payment_run_id}/fund](https://api.weavr.io/products/payment-run/openapi/payment-runs/getpaymentrunsidfund.md): Start the the funding process of a payment run. Specify the funding source of the payment run by providing an id to an already linked account. Depending on the maximum payment amount constraints imposed by the bank that is providing the account, the payment run may be split in 2 or more groups. Note that you'll need to complete a funding process for each instruction returned. Required user role: CONTROLLER ### Cancel a payment run - [POST /v1/payment_runs/{payment_run_id}/cancel](https://api.weavr.io/products/payment-run/openapi/payment-runs/postpaymentrunsidcancel.md): Cancel a payment run. Note that a payment run can be cancelled when it is in the states QUEUED, PENDING_CONFIRMATION, PENDING_CHALLENGE, OR PENDING_FUNDING Required user roles: CONTROLLER OR CREATOR ### Cancel a payment - [PUT /v1/payment_runs/{payment_run_id}/cancel/payments](https://api.weavr.io/products/payment-run/openapi/payment-runs/putcancelpaymentrunpayment.md): Cancel a payment within a payment run. Note that a payment can be cancelled when it is in the state PENDING_CONFIRMATION. Required user roles: CONTROLLER OR CREATOR ### Restart a payment run - [POST /v1/payment_runs/{payment_run_id}/restart](https://api.weavr.io/products/payment-run/openapi/payment-runs/postrestartpaymentrun.md): Restart a payment run after it has entered status SCA_FAILED. Required user role: CONTROLLER ### Cancel a payment run group - [POST /v1/payment_runs/{payment_run_id}/group/{group_reference}/cancel](https://api.weavr.io/products/payment-run/openapi/payment-runs/postcancelpaymentrungroup.md): Cancel a payment run group Note that a payment run group can only be cancelled when it is in the state AWAITING_FUNDS. Required user role: CONTROLLER ## Linked Accounts Linked accounts represent bank accounts that the buyer has with other banks. Once set up, they are used to fund payment runs. ### Get Linked accounts - [GET /v1/linked_accounts](https://api.weavr.io/products/payment-run/openapi/linked-accounts/getlinkedaccounts.md): Retrieves the linked accounts belonging to the buyer that the logged-in user belongs to. Required user role: CONTROLLER ### Get Linked account - [GET /v1/linked_accounts/{linked_account_id}](https://api.weavr.io/products/payment-run/openapi/linked-accounts/getlinkedaccountsid.md): Retrieves a linked account of the buyer that the logged-in user belongs to. Required user role: CONTROLLER ### Update a linked account - [PATCH /v1/linked_accounts/{linked_account_id}](https://api.weavr.io/products/payment-run/openapi/linked-accounts/patchlinkedaccountsid.md): Updates properties of a linked account such as friendly name. Required user role: CONTROLLER ### Unlink a linked account - [POST /v1/linked_accounts/{linked_account_id}/unlink](https://api.weavr.io/products/payment-run/openapi/linked-accounts/unlinklinkedaccountsid.md): Unlinks a linked account identified by the linked_account_id. This action is not reversible and if the buyer wants to use this linked account again to fund payment runs, they will have to re-link the account. More information on how to link an account can be found here. Details of an unlinked account, can still be retrieved via the Get linked accounts and Get linked account endpoints. Required user role: CONTROLLER ## Institutions Institutions supported by Embedded Payment Run. ### Get Institutions - [GET /v1/institutions](https://api.weavr.io/products/payment-run/openapi/institutions/getinstitutions.md): Retrieves the Institutions supported by Embedded Payment Run. The response payload should list all the institutions. Payment runs are funded from linked bank accounts provided by one of the supported institutions. We recommend that you enable Buyers to check if their banks are supported before they start the registration and onboarding process. ## Simulator Simulators enable you to trigger processes in Sandbox that in Production are triggered from an external action rather than from your application. this way you can test scenarios that otherwise you would only encounter in the Live environment. *Note: These endpoints are only available on Sandbox and won’t work in the Live environment.* ### Simulate Fund a Payment run - [POST /simulate/v1/payment_runs/{payment_run_id}/fund_group/{reference}](https://api.weavr.io/products/payment-run/openapi/simulator/postfundpaymentrungroup.md): Simulate funding a payment run using a linked account. This endpoint will only function in Sandbox and should not be used in the Live environment. ### Simulate Creating a Linked Account via Open Banking - [POST /simulate/v1/linked_accounts](https://api.weavr.io/products/payment-run/openapi/simulator/postlinkedaccounts.md): The Linked Account Simulator allows you to create a simulated linked account that can be used for funding payment runs. This endpoint will only function in Sandbox and should not be used in the Live environment. ### Simulate Control Check via Test Funding Transaction - [POST /simulate/v1/linked_accounts/{linked_account_id}/fund](https://api.weavr.io/products/payment-run/openapi/simulator/postsimulatelinkedaccountfundverification.md): Simulate Control Check via Test Funding Transaction ### Simulate Buyer KYB Verify - [POST /simulate/v1/buyers/{buyer_id}/verify](https://api.weavr.io/products/payment-run/openapi/simulator/verifybuyerkyb.md): Simulates due diligence (KYB) for Buyers. This endpoint will only function in Sandbox and should not be used in the Live environment. ### Simulate AIS consent status change - [POST /simulate/v1/consents/{linked_account_id}/change_status](https://api.weavr.io/products/payment-run/openapi/simulator/postsimulateconsentstatuschange.md): Simulate AIS consent status change. This endpoint will only function in Sandbox and should not be used in the Live environment. ### Simulate issuing a Payment Run SCA Challenge - [POST /simulate/v1/payment_run_sca/{payment_run_id}/challenges/otp/{channel}](https://api.weavr.io/products/payment-run/openapi/simulator/issuepaymentrunchallengesimulate.md): Simulates issuing the SCA challenge for a payment run. This endpoint will only function in Sandbox and should not be used in the Live environment. ### Simulate verifying a payment run SCA Challenge - [POST /simulate/v1/payment_run_sca/{payment_run_id}/challenges/otp/{channel}/verify](https://api.weavr.io/products/payment-run/openapi/simulator/verifypaymentrunchallengesimulate.md): Simulates verifying the SCA challenge for a payment run. This endpoint will only function in Sandbox and should not be used in the Live environment. ## Buyers Buyers are identities representing companies. Once on-boarded, Buyers can create and manage their own instruments via your application. ### Buyer KYB status update - [POST buyerKYBWatch](https://api.weavr.io/products/payment-run/openapi/buyers-webhooks/webhook_buyer_kyb_watch.md): Notification that the KYB status of a buyer identity has been updated. ### Buyer Beneficiary status update - [POST buyerBeneficiaryStatusWatch](https://api.weavr.io/products/payment-run/openapi/buyers-webhooks/webhook_buyer_beneficiary_kyb_watch.md): Notification that the verification status of a buyer beneficiary has been updated. ### Buyer update - [POST buyerWatch](https://api.weavr.io/products/payment-run/openapi/buyers-webhooks/webhook_buyer_watch.md): Notification that a buyer has been updated. ### Buyer deactivation - [POST buyerDeactivatedWatch](https://api.weavr.io/products/payment-run/openapi/buyers-webhooks/webhook_buyer_deactivated_watch.md): Notification that a buyer identity has been deactivated. ## Payment runs Notification that the Payment Run and payment statuses have been updated. ### Payment Run Update - [POST paymentRunWatch](https://api.weavr.io/products/payment-run/openapi/payment-runs-webhooks/webhookpaymentrunwatch.md): Notification that the status of a Payment Run has been updated. ### Payment Update - [POST paymentRunPaymentWatch](https://api.weavr.io/products/payment-run/openapi/payment-runs-webhooks/webhookpaymentrunpaymentwatch.md): Notification that the status of a payment in the Payment Run has been updated. ### Payment Run Group Not Funded - [POST paymentRunGroupNotFunded](https://api.weavr.io/products/payment-run/openapi/payment-runs-webhooks/webhookpaymentrungroupnotfunded.md): Notification that a group expecting funds has not been funded. ## Linked Accounts Notification that the status of a Linked Account has been updated. ### Linked Account Update - [POST linkedAccountWatch](https://api.weavr.io/products/payment-run/openapi/linked-accounts-webhooks/webhooklinkedaccountwatch.md): Notification of the status update for a linked Account. ### Linked Account Expiring Soon - [POST linkedAccountExpiringSoonWatch](https://api.weavr.io/products/payment-run/openapi/linked-accounts-webhooks/linkedaccountexpiringsoonwatch.md): Notification when a linked account is expiring soon. ## Login Tokens webhooks ### Login attempt - [POST loginWatch](https://api.weavr.io/products/payment-run/openapi/tokens-webhooks/webhook-login-watch.md): Notification that a login attempt was completed successfully or declined. ## Stepup Notification that a step-up has been completed or declined. ### Step-up status - [POST stepupWatch](https://api.weavr.io/products/payment-run/openapi/stepup-webhooks/stepup_watch.md): Notification that a step-up has been completed or declined. ## Authentication Factors Notification of the Authentication Factors that are used for the `Identity`. ### Enrolment status - [POST authenticationFactorsWatch](https://api.weavr.io/products/payment-run/openapi/authentication-factors-webhooks/authentication_factors_watch.md): Notification that an enrolment has been accepted or declined. ## Transactions Notification that the status of a transaction has been updated. ### Sweeping status update - [POST sweepingWatch](https://api.weavr.io/products/payment-run/openapi/transactions-webhooks/sweeping_watch.md): Notification that the sweeping status has been updated. Sweeping represents transactions that return money to the source account. It may be triggered by unmatched incoming transaction or by failed payment run payments.