# 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 - [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 se - [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 - [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. - [POST /v1/passwords/update](https://api.weavr.io/products/payment-run/openapi/passwords/passwordupdate.md): Update the password for the logged-in user. - [POST /v1/passwords/validate](https://api.weavr.io/products/payment-run/openapi/passwords/passwordvalidate.md): Check that a password adheres to all complexity checks. - [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 c - [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 - [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-t - [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 ## Step up - [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}` - [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 - [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 fo - [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` - [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` - [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 *bu - [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 v - [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 belong - [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` - [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 verifi ## Buyer Authorised Users - [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 c - [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 /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` - [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 o - [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-acti - [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-act - [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 t - [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). - [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 - [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 - [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 ## Payment runs - [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 enable - [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 /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` - [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` - [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 /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 impos - [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 - [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` - [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` - [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 - [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 /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` - [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` - [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 th ## 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 supporte ## Simulator - [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.* - [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 - [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 - [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.* - [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.* - [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.* - [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 - [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. - [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. - [POST buyerWatch](https://api.weavr.io/products/payment-run/openapi/buyers-webhooks/webhook_buyer_watch.md): Notification that a buyer has been updated. - [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 - [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. - [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. - [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 - [POST linkedAccountWatch](https://api.weavr.io/products/payment-run/openapi/linked-accounts-webhooks/webhooklinkedaccountwatch.md): Notification of the status update for a linked Account. - [POST linkedAccountExpiringSoonWatch](https://api.weavr.io/products/payment-run/openapi/linked-accounts-webhooks/linkedaccountexpiringsoonwatch.md): Notification when a linked account is expiring soon. ## Login - [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 - [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 - [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 - [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 pa