openapi: 3.2.0 info: version: v1 title: Weavr Embedded Payment Run Buyers Webhooks API license: name: private url: https://weavr.io x-logo: url: https://weavr-cdn.s3.eu-central-1.amazonaws.com/weavr-payment-run-logo.png backgroundColor: '#FFFFFF' altText: Weavr description: "Weavr Payment Run Plug-in API provides a simple and flexible way for Embedders to add payment execution capabilities in their application.\n\nBy 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.\n\n# Authentication\nEach 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).\n\nAlmost all endpoints require a secondary authentication token `auth_token` that represents the user for whom the request is being executed.\n\n# Postman Collection\nTo 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. \n\nThe 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).\n" servers: - url: https://sandbox.weavr.io/payment-run description: Sandbox security: - apiKey: [] authToken: [] tags: - name: Buyers Webhooks description: Buyers are identities representing companies. Once on-boarded, Buyers can create and manage their own instruments via your application. x-displayName: Buyers paths: {} webhooks: buyerKYBWatch: post: summary: Buyer KYB status update description: Notification that the KYB status of a buyer identity has been updated. operationId: webhook_buyer_kyb_watch security: [] tags: - Buyers Webhooks parameters: - name: call-ref in: header description: 'A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255 ' required: false style: simple explode: false schema: type: string - name: published-timestamp in: header description: The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published. required: true style: simple explode: false schema: type: integer format: int64 - name: signature in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key. required: true style: simple explode: false schema: type: string - name: signature-v2 in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `call-ref` header, the request body, and the `published-timestamp` header, all concatenated without spaces, and signed using your API key. required: true style: simple explode: false schema: type: string requestBody: content: application/json: schema: type: object properties: type: type: string enum: - buyerKYBWatch payload: type: object properties: buyerId: type: string pattern: ^[0-9]+$ description: Id of the buyer. status: type: string enum: - NOT_STARTED - INITIATED - PENDING_REVIEW - APPROVED - REJECTED description: Effective KYB status of the buyer. details: type: array description: Action which my be required to re-process kyb in case of temporary rejections. items: type: string enum: - BUYER_DETAILS_UNSATISFACTORY - ADMIN_USER_UNMATCHED_TO_DIRECTOR_OR_REPRESENTATIVE - UNDEFINED_REQUIRED_INTERVENTION - DOCUMENTS_UNSATISFACTORY - SUPPLIED_DATA_AND_DOCUMENTS_MISMATCH - LANGUAGE_IN_DOCUMENTS_UNSUPPORTED - SELFIE_UNSATISFACTORY - SELFIE_AND_DOCUMENTS_MISMATCH - BENEFICIARY_DETAILS_UNSATISFACTORY - REPRESENTATIVE_DETAILS_UNSATISFACTORY - OTHER - UNSUPPORTED_COUNTRY - EXPIRED_KYC_DOCUMENTS rejectionComment: type: string description: Reason shown to the user in case of temporary rejection. ongoingStatus: type: string enum: - NOT_STARTED - INITIATED - PENDING_REVIEW - APPROVED - REJECTED description: Ongoing KYB Status of the buyer. required: true responses: '200': description: Return a 200 status to indicate that the data was received successfully buyerBeneficiaryStatusWatch: post: summary: Buyer Beneficiary status update description: Notification that the verification status of a buyer beneficiary has been updated. operationId: webhook_buyer_beneficiary_kyb_watch security: [] tags: - Buyers Webhooks parameters: - name: call-ref in: header description: 'A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255 ' required: false style: simple explode: false schema: type: string - name: published-timestamp in: header description: The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published. required: true style: simple explode: false schema: type: integer format: int64 - name: signature in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key. required: true style: simple explode: false schema: type: string - name: signature-v2 in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `call-ref` header, the request body, and the `published-timestamp` header, all concatenated without spaces, and signed using your API key. required: true style: simple explode: false schema: type: string requestBody: content: application/json: schema: type: object properties: type: type: string enum: - buyerBeneficiaryStatusWatch payload: type: object properties: event: type: array description: 'The event that triggered this webhook notification. The event is structured to describe the parameter that has triggered the event followed by the action that occurred. ' items: type: string enum: - STATUS_UPDATED - BENEFICIARY_TYPE_UPDATED - FIRST_NAME_UPDATED - MIDDLE_NAME_UPDATED - LAST_NAME_UPDATED - EMAIL_UPDATED eventDetails: type: array description: A reason, if any, describing why this event has occurred. items: type: string enum: - BUYER_DETAILS_UNSATISFACTORY - ADMIN_USER_UNMATCHED_TO_DIRECTOR_OR_REPRESENTATIVE - UNDEFINED_REQUIRED_INTERVENTION - DOCUMENTS_UNSATISFACTORY - SUPPLIED_DATA_AND_DOCUMENTS_MISMATCH - LANGUAGE_IN_DOCUMENTS_UNSUPPORTED - SELFIE_UNSATISFACTORY - SELFIE_AND_DOCUMENTS_MISMATCH - BENEFICIARY_DETAILS_UNSATISFACTORY - REPRESENTATIVE_DETAILS_UNSATISFACTORY - OTHER - UNSUPPORTED_COUNTRY - EXPIRED_KYC_DOCUMENTS additionalInformation: type: object properties: buyerId: type: string pattern: ^[0-9]+$ description: The buyer id whose beneficiary has triggered this event. buyerName: type: string description: The buyer name whose beneficiary has triggered this event. adminUserEmail: type: string description: The buyer's root user email. kybStatus: type: string enum: - NOT_STARTED - INITIATED - PENDING_REVIEW - APPROVED - REJECTED description: The status of the Full Company Verification Checks for the buyer entity. beneficiary: type: object properties: type: type: string enum: - UNDEFINED_BENEFICIARY_TYPE - UBO - DIRECTOR - UNKNOWN - SHAREHOLDER - PARTNER - OTHER_DIRECTOR description: Type of the beneficiary. firstName: type: string description: First name of the beneficiary. middleName: type: string description: Middle name of the beneficiary. lastName: type: string description: Last name of the beneficiary. email: type: string description: Email of the beneficiary. status: type: string enum: - NOT_STARTED - INITIATED - PENDING_REVIEW - APPROVED - REJECTED description: Effective KYB Status of the beneficiary. ongoingKybStatus: type: string enum: - NOT_STARTED - INITIATED - PENDING_REVIEW - APPROVED - REJECTED description: Ongoing KYB Status of the beneficiary. description: Additional information related to the event triggering this notification. rejectionComment: type: string description: Reason shown to the user in case of temporary rejection. required: true responses: '200': description: Return a 200 status to indicate that the data was received successfully buyerWatch: post: summary: Buyer update description: Notification that a buyer has been updated. operationId: webhook_buyer_watch security: [] tags: - Buyers Webhooks parameters: - name: call-ref in: header description: 'A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255 ' required: false style: simple explode: false schema: type: string - name: published-timestamp in: header description: The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published. required: true style: simple explode: false schema: type: integer format: int64 - name: signature in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key. required: true style: simple explode: false schema: type: string - name: signature-v2 in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `call-ref` header, the request body, and the `published-timestamp` header, all concatenated without spaces, and signed using your API key. required: true style: simple explode: false schema: type: string requestBody: content: application/json: schema: type: object properties: type: type: string enum: - buyerActivatedWatch payload: required: - actionDoneBy - buyerId - supportedCurrencies type: object properties: actionDoneBy: type: string enum: - UNDEFINED - ADMIN - EMBEDDER buyerId: type: string supportedCurrencies: type: array items: type: object required: - currency - status properties: currency: type: string description: The currency expressed in ISO-4217 code. maxLength: 3 minLength: 3 enum: - GBP - EUR status: type: string description: 'The status of the currency, which can include the following values * `PENDING_KYB_APPROVAL`: The buyer’s KYB process is pending approval. * `STEPUP_LOGIN_REQUIRED`: The buyer needs to perform a stepped-up login for higher authentication. * `PENDING_CREATION`: Awaiting the setup completion of the currency * `ACTIVE`: The ZBA has been successfully created and is ready for use. * `UNAVAILABLE`: The currency is unavailable and cannot be used. ' enum: - PENDING_KYB_APPROVAL - STEPUP_LOGIN_REQUIRED - PENDING_CREATION - ACTIVE - UNAVAILABLE required: true responses: '200': description: Return a 200 status to indicate that the data was received successfully buyerDeactivatedWatch: post: summary: Buyer deactivation description: Notification that a buyer identity has been deactivated. operationId: webhook_buyer_deactivated_watch security: [] tags: - Buyers Webhooks parameters: - name: call-ref in: header description: 'A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255 ' required: false style: simple explode: false schema: type: string - name: published-timestamp in: header description: The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published. required: true style: simple explode: false schema: type: integer format: int64 - name: signature in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key. required: true style: simple explode: false schema: type: string - name: signature-v2 in: header description: The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the `call-ref` header, the request body, and the `published-timestamp` header, all concatenated without spaces, and signed using your API key. required: true style: simple explode: false schema: type: string requestBody: content: application/json: schema: type: object properties: type: type: string enum: - buyerDeactivatedWatch payload: required: - actionDoneBy - buyerId - reasonCode - supportedCurrencies type: object properties: actionDoneBy: type: string enum: - UNDEFINED - ADMIN - EMBEDDER buyerId: type: string reasonCode: type: string enum: - UNDEFINED_REASON - ACCOUNT_REVIEW - ACCOUNT_SECURITY - TEMPORARY - ACCOUNT_CLOSURE - ACCOUNT_ABANDONED supportedCurrencies: type: array items: type: object required: - currency - status properties: currency: type: string description: The currency expressed in ISO-4217 code. maxLength: 3 minLength: 3 enum: - GBP - EUR status: type: string description: 'The status of the currency, which can include the following values * `PENDING_KYB_APPROVAL`: The buyer’s KYB process is pending approval. * `STEPUP_LOGIN_REQUIRED`: The buyer needs to perform a stepped-up login for higher authentication. * `PENDING_CREATION`: Awaiting the setup completion of the currency * `ACTIVE`: The ZBA has been successfully created and is ready for use. * `UNAVAILABLE`: The currency is unavailable and cannot be used. ' enum: - PENDING_KYB_APPROVAL - STEPUP_LOGIN_REQUIRED - PENDING_CREATION - ACTIVE - UNAVAILABLE required: true responses: '200': description: Return a 200 status to indicate that the data was received successfully components: securitySchemes: apiKey: name: api-key type: apiKey in: header description: The API Key representing your Weavr account. You can find your API Key in your Weavr Portal in the API Credentials page. authToken: type: http description: The authentication token representing the user. This will be included in the login response object. scheme: bearer bearerFormat: JWT x-tagGroups: - name: Authentication tags: - Tokens - Passwords - name: Authorisation tags: - Additional Factors - Step up - name: Identities tags: - Buyers - Buyer Authorised Users - name: Payment runs tags: - Payment runs - name: Instruments tags: - Linked Accounts - name: Institutions tags: - Institutions - name: Simulators tags: - Simulator - name: Events tags: - Buyers Webhooks - Payment runs Webhooks - Linked Accounts Webhooks - Tokens Webhooks - Stepup Webhooks - Authentication Factors Webhooks - Transactions Webhooks