[ { "product": "collect", "id": "hosted-page-card-token-object", "type": "type", "name": "HostedPageCardToken", "description": "The Hosted Page Card object provides a hosted page where a customer saves card details and manages cards. The customer can add cards, delete cards, and select a card as the default payment method. \n\nWhen the customer uses the hosted page, a card token is created or updated. The default payment method is associated with the relevant card token and with the customer ID. \n\nYou can use the default card token (starts with **card_**) or the customer ID (starts with **cus_**) for billing. PCI certification is not required.\n\nThe hosted page expires 14 days after creation.", "fields": [ { "name": "id", "type": [ { "type": "string" } ], "description": "ID of the Hosted Page Card Token object, a string starting with **hp\\_card\\_**. Response only.", "required": true }, { "description": "Indicates whether the hosted page displays address fields to fill in. \n\\* **true** - The fields are displayed. \n\\* **false** - The fields are displayed only for country codes **US**, **GB** and **CA**. This is the default.", "name": "billing_address_collect", "type": [ { "type": "boolean" } ], "required": true }, { "name": "cancel_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL.", "required": true }, { "name": "cards", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "Reserved. Response only.", "required": true }, { "name": "category", "type": [ { "type": "string" } ], "description": "Category of payment method: **card**. Response only.", "required": true }, { "name": "complete_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected after pressing **Close** to exit the hosted page. This URL overrides the `merchant_website` URL.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "When specified in the request, defines a currency that is not the country's default currency. \nWhen not specified in the request, the country's default currency. \nThree-letter ISO 4217 code.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer, a string starting with **cus_**.\n\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "expiration", "description": "Time when the hosted page URL expires, in [*Unix time*](ref:glossary). 14 days after creation of the page. Response only.", "type": [ { "type": "number" } ], "required": true }, { "name": "language", "type": [ { "type": "string" } ], "description": "Determines the default language of the hosted page. \nThe values are listed on [Hosted Page Language Support](ref:hosted-page-language-support).", "required": true }, { "name": "merchant_customer_support", "type": [ { "type": "object", "fields": [ { "name": "email", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] }, { "name": "phone_number", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contact details for customer support, containing the following fields:\n\\* `email` - Email address.\n\\* `url` - URL for the client's customer support service.\n\\* `phone_number` - Phone number for contacting the client's customer support service. \n\nResponse only.\n\nTo configure these fields, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/client-portal/docs/customizing-your-hosted-page).", "required": true }, { "name": "merchant_website", "type": [ { "type": "string" } ], "description": "The URL where the customer is redirected after exiting the hosted page. \n\nRelevant when one or both of the following fields is unset: \n\\* `cancel_url`\n\\* `complete_url`\n\nResponse only.\n\nTo configure this field, use the **Fallback URL** field in the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/client-portal/docs/customizing-your-hosted-page).", "required": true }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "description": "Limits the page to a specific type of payment method. For example, **dk_visa_card**. For a list of payment methods, use [List Payment Methods by Country](ref:list-payment-methods-by-country).", "required": true }, { "name": "payment_method_types", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "Reserved. Response only.", "required": true }, { "name": "payment_params", "type": [ { "type": "object", "fields": [ { "name": "complete_payment_url", "type": [ { "type": "unknown" } ] }, { "name": "error_payment_url", "type": [ { "type": "unknown" } ] } ] } ], "description": "Reserved. Contains the following fields:\n\\* `complete_payment_url` \n\\* `error_payment_url` \n\nResponse only.", "required": true }, { "name": "redirect_url", "description": "URL of the hosted page. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "NEW", "DONE" ] } ], "description": "Status of the hosted page. One of the following:\n\\* **NEW** - The page was created.\n\\* **DONE** - A card was added.\n\nResponse only.", "required": true }, { "name": "timestamp", "description": "Time when the hosted page is created, in [*Unix time*](ref:glossary). Response only.", "type": [ { "type": "number" } ], "required": true } ] }, { "product": "collect", "id": "bank-account-token-object", "type": "type", "name": "BankAccountToken", "description": "", "fields": [ { "name": "data", "type": [ { "type": "object" } ], "description": "See ***Data Object Fields***, below.", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Type of token. **bank_account**", "required": true } ] }, { "product": "collect", "id": "pii-token-object", "type": "type", "name": "PIIToken", "description": "A PII token represents Personally Identifiable Information (*[PII](ref:glossary)*). Defined by the merchant.", "fields": [ { "name": "data", "type": [ { "type": "object" } ], "description": "See ***Data Object Fields***, below.", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Type of token. For a PII token: **pii**", "required": true } ] }, { "product": "collect", "id": "escrow-object", "type": "type", "name": "Escrow", "description": "The Escrow object represents the funds held in escrow for later release. It is created when the payment is created.", "fields": [ { "description": "ID of the escrow, a string starting with **escrow_**.", "type": [ { "type": "string", "startsWith": "escrow_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount in escrow, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.", "required": true }, { "name": "amount_on_hold", "type": [ { "type": "number" } ], "description": "Total amount of funds that are currently held in the escrow, in the currency defined in `currency_code`.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Date and time the escrow was created, in [*Unix time*](ref:glossary).", "required": true }, { "description": "ID of the escrow, a string starting with **escrow_**.", "name": "escrow", "type": [ { "type": "string", "startsWith": "escrow_" } ], "required": true }, { "name": "escrow_release_days", "type": [ { "type": "number" } ], "description": "Indicates the number of days after creation of the payment that funds are released from escrow. Funds are released at 5:00 pm GMT on the day indicated. Integer, range: 1-90.", "required": true }, { "name": "escrow_releases", "type": [ { "type": "array" } ], "description": "Array of objects that describe individual releases.\n\nSee ***Escrow Releases Object***, below.", "required": true }, { "name": "ewallets", "type": [ { "type": "array" } ], "description": "Array of objects that define the allocation of the release to multiple wallets. Each object contains the following fields:\n* `ewallet` - ID of the wallet, a string starting with 'ewallet_'.\n* `amount` - The amount to release to this wallet. Relevant when `percentage` is not set.\n* `percentage` - The percentage of this escrow to release to this wallet. Relevant when `amount` is not set. On a partial release after the first, this refers to the percentage of the original amount of the escrow.\n\n**Note:** All wallets in the array must be specified by `amount` or by `percentage` or neither. If neither `amount` nor `percentage` is set, the release is proportionate according to the split defined in the payment.", "required": true }, { "name": "last_payment_completion", "type": [ { "type": "number" } ], "description": "Date and time of the completion of the last payment or partial payment, in [*Unix time*](ref:glossary).", "required": true }, { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "description": "ID of the payment, a string starting with **payment_**.", "required": true }, { "type": [ { "type": "number" } ], "description": "The percentage that is paid to the wallet out of the total payment. Positive decimal, up to 3 decimal places. If the amount is a whole number, use an integer and not a decimal. Maximum value: 100.", "name": "percentage", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "pending", "on_hold", "canceled", "released" ] } ], "description": "Status of the escrow. One of the following:\n* **pending** - The payment and escrow were created, but the payment is not completed and the funds are not in the escrow.\n* **on_hold** - The payment is completed and the funds are in escrow.\n* **canceled** - The escrow is canceled.\n* **released** - All or part of the funds have been released to the wallets.", "required": true }, { "name": "total_amount_released", "type": [ { "type": "number" } ], "description": "Total amount of funds that were released to the wallets, in the currency defined in `currency_code`.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Date and time of the last update to the escrow, in [*Unix time*](ref:glossary).", "required": true }, { "name": "receipt_number", "type": [ { "type": "string" } ], "description": "Number of the receipt for the refund, provided by the merchant. Read-only.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "Completed", "Rejected", "Pending" ] } ], "description": "Indicates the status of the refund operation. One of the following values:\n* **Completed** - The refund was complete.\n* **Rejected** - The refund was not made because of an internal error.\n* **Pending** - The request created a refund object on the Rapyd platform, but the refund is not yet complete. For example, the refund is for a payment method that requires a customer action, such as cash, bank redirect or bank transfer.\n\nRead-only.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Time that this refund was last updated, in [*Unix time*](ref:glossary). Read-only.", "required": true } ] }, { "product": "collect", "parent": "escrow-object", "id": "retrieve-escrow", "type": "request", "name": "RetrieveEscrowRequest", "description": "Use the GET method to retrieve details of the escrow for a payment.", "method": "GET", "path": "/v1/payments/{payment}/escrows/{escrow}", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." }, { "name": "escrow", "type": [ { "type": "string", "startsWith": "escrow_" } ], "required": true, "description": "ID of the escrow. String starting with **escrow_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "escrow-object", "id": "release-funds-from-escrow", "type": "request", "name": "ReleaseFundsFromEscrowRequest", "description": "Use the POST method to release funds from escrow. The status of the escrow must be 'pending' or 'released'. When the funds are transferred into escrow via partial payments, this method releases all funds currently in the escrow.\n\nThis method triggers the **Escrow Released** webhook. See [Webhook - Escrow Released](ref:webhook-escrow-released).", "method": "POST", "path": "/v1/payments/{payment}/escrows/{escrow}/escrow_releases", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." }, { "name": "escrow", "type": [ { "type": "string", "startsWith": "escrow_" } ], "required": true, "description": "ID of the escrow. String starting with **escrow_**." } ], "body": [ { "name": "ewallets", "type": [ { "type": "string" } ], "required": false, "description": "A list of objects. Each object contains an `ewallet` field, and optionally 'amount' or 'percentage'." }, { "name": "percentage", "type": [ { "type": "string" } ], "required": false, "description": "Determines the percentage of the escrow to release." }, { "name": "amount", "type": [ { "type": "string" } ], "required": false, "description": "Determines the amount to release from escrow." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "escrow-object", "id": "list-escrow-releases", "type": "request", "name": "ListEscrowReleasesRequest", "description": "Use the GET method to retrieve a list of all releases of funds from an escrow.", "method": "GET", "path": "/v1/payments/{payment}/escrows/{escrow}/escrow_releases", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." }, { "name": "escrow", "type": [ { "type": "string", "startsWith": "escrow_" } ], "required": true, "description": "ID of the escrow. String starting with **escrow_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "escrow-object", "id": "escrow-errors", "type": "enum", "name": "EscrowError", "values": [ { "name": "ERROR_CARD_VALIDATION_IN_PAYMENT_WITH_ESCROW", "description": "The request attempted to validate a card as part of an escrow transaction, but these two operations must be done separately. The request was rejected. Corrective action: Create a payment with a card payment method, set 'capture' to false, set 'amount’ to 0, and set 'escrow' to null. Next, create the payment with the escrow." }, { "name": "ERROR_ESCROW_ALREADY_RELEASED", "description": "The request tried to update a payment and reset 'escrow_release_days', but funds were already released. The request was rejected. Corrective action: Make future releases from this escrow manually." }, { "name": "ERROR_ESCROW_RELEASE_DAYS_NOT_VALID", "description": "The request tried to set the number of days for release of an escrow, but the number was out of range. The request was rejected. Corrective action: For 'escrow_release_days', use an integer between 1 and 90." }, { "name": "ERROR_GET_ESCROW", "description": "The request attempted an operation that requires a payment and its escrow, but the payment or the escrow was not found. The request was rejected. Corrective action: Use a valid ID for the payment and for the escrow." }, { "name": "ERROR_PAYMENT_ESCROW_RELEASE_DAYS_NOT_APPLICABLE", "description": "The request tried to create a payment that does not involve an escrow, but 'escrow_release_days' was set. The request was rejected. Corrective action: Set 'escrow_release_days' to null." }, { "name": "ERROR_PREVIOUS_RELEASE_FROM_ESCROW_WAS_NOT_PROPORTIONATE", "description": "The request tried to do a proportionate partial release of an escrow to multiple wallets, but there was a previous partial release by percentage or by specific amounts. The request was rejected. Corrective action: In the body of the request, provide an array of wallets, and for each wallet, indicate its ID and the specific 'percentage' or 'amount' to release." }, { "name": "ERROR_RELEASE_ESCROW_DUPLICATE_EWALLET", "description": "The request tried to release an escrow, but one wallet appeared more than one time. The request was rejected. Corrective action: In the array of wallets, list each wallet only one time." }, { "name": "ERROR_RELEASE_ESCROW_EWALLET_ALREADY_FULLY_RELEASED", "description": "The request tried to release an escrow, but the entire amount of the payment was already released, or the entire portion allotted to one wallet was already released. The request was rejected. Corrective action: None. Determine why an attempt was made to release more funds than was specified in the payment." }, { "name": "ERROR_RELEASE_ESCROW_EWALLET_AMOUNT_EXCEEDS_ORIGINAL_SPLIT", "description": "The request tried to release an escrow, but the amount specified for one of the wallets and the amount previously released to that wallet was greater than the amount set in the payment for that wallet. The request was rejected. Corrective action: For each wallet in the 'ewallets' array, set an amount that is less than or equal to the amount set in the payment." }, { "name": "ERROR_RELEASE_ESCROW_EWALLET_NOT_FOUND_IN_PAYMENT", "description": "The request tried to release an escrow, but one of the wallets was not specified when the payment was created. The request was rejected. Corrective action: In the 'ewallets' array, specify only wallets that were part of the payment." }, { "name": "ERROR_RELEASE_ESCROW_EWALLETS_CANNOT_SET_BOTH_AMOUNT_AND_PERCENTAGE", "description": "The request tried to release an escrow, but the amount released to one of the wallets was specified by both amount and percentage. The request was rejected. Corrective action: In the 'ewallet' object, specify 'amount' or 'percentage' or neither. If you specify neither, the amounts will be released to the wallets in proportion to the amounts defined in the payment." }, { "name": "ERROR_RELEASE_ESCROW_EWALLETS_INCONSISTENCY", "description": "The request tried to release an escrow to multiple wallets, but the method of determining the amounts was not the same for all the wallets. The request was rejected. Corrective action: For all of the wallets in the 'ewallets' array, use 'amount' or 'percentage' or neither. If you specify neither, the amounts will be released to the wallets in proportion to the amounts defined in the payment." }, { "name": "ERROR_RELEASE_ESCROW_INVALID_AMOUNT", "description": "The request tried to release an escrow, but the amount was not recognized. The request was rejected. Corrective action: For 'amount', use a positive decimal number." }, { "name": "ERROR_RELEASE_ESCROW_INVALID_EWALLETS_AMOUNT", "description": "The request tried to release an escrow, but the amount for one of the wallets was not a positive decimal number. The request was rejected. Corrective action: For 'amount', use a positive decimal number." }, { "name": "ERROR_RELEASE_ESCROW_INVALID_EWALLETS_PERCENTAGE", "description": "The request tried to release an escrow, but the amount for one of the wallets was not recognized. The request was rejected. Corrective action: For 'percentage', use a positive decimal number less than 100, with up to two decimal places." }, { "name": "ERROR_RELEASE_ESCROW_INVALID_PERCENTAGE", "description": "The request tried to release an escrow, but the allocation by percentage was not recognized. The request was rejected. Corrective action: For 'percentage' in each object in the 'ewallets' array, use a positive decimal number less than 100, with up to two decimal places." }, { "name": "ERROR_RELEASE_ESCROW_MISSING_EWALLET_ID", "description": "The request tried to release an escrow, but one of the wallets was not found. The request was rejected. Corrective action: In the 'ewallets' array, use IDs of valid wallets." }, { "name": "ERROR_RELEASE_ESCROW_MUST_SET_AMOUNT_OR_PERCENTAGE_OR_EWALLETS", "description": "The request tried to release an escrow, but the method of distributing the funds was unclear. The request was rejected. Corrective action: Specify one of the following fields: 'amount', 'percentage', 'ewallets', or none of them." }, { "name": "ERROR_RELEASE_ESCROW_NO_FUNDS_ON_HOLD", "description": "The request tried to release funds from an escrow, but there are no funds on hold. The request was rejected. Corrective action: Release funds from escrow when there are funds on hold." }, { "name": "ERROR_RELEASE_ESCROW_NOT_ENOUGH_FUNDS_ON_HOLD", "description": "The request tried to release an escrow, but the amount specified was more than the amount on hold. The request was rejected. Corrective action: Use 'amount' or 'percentage' or neither to define the release so that the amount released is less than or equal to the amount on hold." }, { "name": "ERROR_RELEASE_ESCROW_STATUS", "description": "The request tried to release funds from an escrow, but the status of the escrow does not allow release. The request was rejected. Corrective action: Release funds from escrow when the 'status' of the escrow is 'released' or 'on_hold'." } ] }, { "product": "collect", "id": "invoice-item-object", "type": "type", "name": "InvoiceItem", "description": "An invoice item represents one product, either goods or services. It can represent two or more identical products at the same price, and the total amount of the invoice item is the `quantity` times the `unit_amount`.\n\nThe item is added to the customer's next invoice that has the same currency.", "fields": [ { "description": "ID of the Invoice Item object.", "type": [ { "type": "string" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount of the total charge or credit for this item. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.\n\nThis is `quantity` times `unit_amount`. A credit is indicated by a negative number.", "required": true }, { "type": [ { "type": "string" } ], "name": "currency", "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer. String starting with **cus_**.\n\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "date", "type": [ { "type": "number" } ], "description": "The time of the charge or credit, in [*Unix time*](ref:glossary).", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the invoice item.", "required": true }, { "name": "discountable", "type": [ { "type": "boolean" } ], "description": "Determines whether this invoice item is subject to the discount defined in the coupon that is assigned to the customer or subscription.\n\nFor negative amounts and prorations, the default is **false**, and for all other invoice items, the default is **true**.", "required": true }, { "name": "invoice", "type": [ { "type": "string" } ], "description": "ID of the invoice that this invoice item is assigned to. Relevant when `subscription` is not set.", "required": true }, { "name": "metadata", "description": "A JSON object defined by the client.", "type": [ { "type": "object" } ], "required": true }, { "name": "period", "description": "Defines the start and end of the time period that this invoice item refers to. Relevant when the invoice item refers to more than one day. Contains the following fields:\n* `start` - The start of the time period.\n* `end` - The end of the time period.", "type": [ { "type": "object", "fields": [ { "name": "start", "type": [ { "type": "unknown" } ] }, { "name": "end", "type": [ { "type": "unknown" } ] } ] } ], "required": true }, { "name": "plan", "type": [ { "type": "object" } ], "description": "Describes the pricing structure for the invoice item.\n\nFor more information, see [Plan Object](#plan-object).", "required": true }, { "name": "proration", "description": "Indicates whether the invoice item is prorated. Response only.", "type": [ { "type": "boolean" } ], "required": true }, { "name": "quantity", "type": [ { "type": "number" } ], "description": "Indicates the number of units charged as a single invoice item. Integer.", "required": true }, { "name": "subscription", "type": [ { "type": "string" } ], "description": "ID of the subscription to assign this invoice item to. By default, the invoice item is assigned to the customer's subscription whose current billing cycle ends first. Relevant when `invoice` is not set.\n\nFor more information, see [Subscription Object](ref:subscription-object).", "required": true }, { "name": "unit_amount", "type": [ { "type": "number" } ], "description": "Per-unit price of the product or service, adjusted as defined in the plan. Decimal.", "required": true } ] }, { "product": "collect", "parent": "invoice-item-object", "id": "create-invoice-item", "type": "request", "name": "CreateInvoiceItemRequest", "description": "Use the POST method to create an invoice item.\n\n**Note:** If the invoice item is created without specifying the invoice, it is attached to the customer's next invoice.\n\nThis method triggers the **Invoice Item Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/invoice_items", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the charge or credit. Decimal. Required when `quantity` and `unit_amount` are not provided." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in the `amount` and `unit_amount` fields. Uppercase." }, { "name": "customer", "type": [ { "type": "string" } ], "required": true, "description": "ID of the customer." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the line item." }, { "name": "discountable", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether this line item is subject to discounts." }, { "name": "invoice", "type": [ { "type": "string" } ], "required": false, "description": "ID of the invoice that this invoice item is assigned to. Relevant when `subscription` is not set." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "quantity", "type": [ { "type": "number" } ], "required": false, "description": "Indicates the number of units charged as a single line item. Required when `amount` is not provided" }, { "name": "subscription", "type": [ { "type": "string" } ], "required": false, "description": "ID of the subscription to assign this invoice item to. By default, the invoice item is assigned to the subscription whose current billing cycle ends first. Relevant when `invoice` is not set." }, { "name": "unit_amount", "type": [ { "type": "number" } ], "required": false, "description": "Per-unit price of the product or service. Required when `amount` is not provided. Decimal." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-item-object", "id": "update-invoice-item", "type": "request", "name": "UpdateInvoiceItemRequest", "description": "Use the POST method to change or modify an invoice item. You can update an invoice item at any time before the corresponding subscription generates an invoice.\n\nThis method triggers the **Invoice Item Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/invoice_items/{invoice_item}", "params": [ { "name": "invoice_item", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice item." } ], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the charge or credit. Decimal." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the line item." }, { "name": "discountable", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether this line item is subject to discounts." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "quantity", "type": [ { "type": "number" } ], "required": false, "description": "Indicates the number of units charged as a single line item." }, { "name": "unit_amount", "type": [ { "type": "number" } ], "required": false, "description": "Per-unit price of the product or service. Decimal." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-item-object", "id": "retrieve-invoice-item", "type": "request", "name": "RetrieveInvoiceItemRequest", "description": "Use the GET method to retrieve the details of an invoice item.", "method": "GET", "path": "/v1/invoice_items/{invoice_item}", "params": [ { "name": "invoice_item", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice item." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-item-object", "id": "list-invoice-items", "type": "request", "name": "ListInvoiceItemsRequest", "description": "Use the GET method to retrieve a list of all invoice items.", "method": "GET", "path": "/v1/invoice_items", "params": [], "body": [], "headers": [], "query": [ { "name": "created", "type": [ { "type": "string" } ], "required": false, "description": "Date of creation of the invoice items." }, { "name": "customer", "type": [ { "type": "string" } ], "required": false, "description": "ID of the customer." }, { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the invoice item created after the last invoice item you want to retrieve." }, { "name": "invoice", "type": [ { "type": "string" } ], "required": false, "description": "ID of the invoice." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of invoice items to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the invoice item created before the first invoice item you want to retrieve." } ] }, { "product": "collect", "parent": "invoice-item-object", "id": "delete-invoice-item", "type": "request", "name": "DeleteInvoiceItemRequest", "description": "Use the DELETE method to delete an invoice item from the upcoming invoice. Use this method in the following situations:\n> \\* The invoice item is attached to an invoice.\n> \\* The invoice item is not attached to an invoice.\n\nThis method triggers the **Invoice Item Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/invoice_items/{invoice_item}", "params": [ { "name": "invoice_item", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice item you want to delete." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-item-object", "id": "invoice-item-errors", "type": "enum", "name": "InvoiceItemError", "values": [ { "name": "ERROR_DELETE_INVOICE_ITEMS", "description": "The request tried to delete an invoice item, but the invoice item was not found. The request was rejected. Corrective action: Determine whether the invoice item was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_INVOICE_ITEMS", "description": "The request tried to retrieve an invoice item, but the invoice item was not found. The request was rejected. Corrective action: Use a valid invoice item ID." }, { "name": "ERROR_INVOICE_ITEM_AMOUNT_PARAM", "description": "The request tried to create an invoice item, but the amount was not was not clear. The request was rejected. Corrective action: Specify the 'amount' field, or specify both 'unit_amount' and 'quantity'." }, { "name": "ERROR_INVOICE_ITEM_CURRENCY_MISMATCH", "description": "The request tried to create an invoice item, but there is no upcoming scheduled invoice with matching currency. The request was rejected. Corrective action: For 'currency', use the currency of the subscription's plan." }, { "name": "ERROR_INVOICE_ITEM_CURRENCY_NO_MATCHING_UPCOMING_INVOICE", "description": "The request tried to create a Invoice item with, but there is no upcoming scheduled invoice with matching currency to be added to . The request was rejected. Corrective action: Create invoice item with matching subscription's plan currency." }, { "name": "ERROR_INVOICE_ITEM_NOT_FOUND", "description": "The request attempted an operation that requires an invoice item, but the invoice item was not found. The request was rejected. Corrective action: Use the ID of a valid invoice item." }, { "name": "ERROR_INVOICE_ITEM_SUBSCRIPTION_TYPE", "description": "The request tried to create an invoice item for a payout subscription, but this action is not possible. The request was rejected. Corrective action: None. Determine why an attempt was made to create an invoice item for a payout subscription." }, { "name": "INVALID_INVOICE_ITEM_ID", "description": "The request tried to update or delete an invoice item, but the invoice item could not be found. The request was rejected. Corrective action: Use the correct ID for a valid invoice item." } ] }, { "product": "disburse", "id": "payout-method-type-object", "type": "type", "name": "PayoutMethodType", "description": "The Payout Method Type object describes a method of payout that can be used in the Rapyd platform.", "fields": [ { "name": "amount_range_per_currency", "description": "An array of objects that describe limits on the amount, per currency. Contains the following fields:\n* `maximum_amount` - Maximum amount supported by this payout method for the indicated currency. Decimal number.\n* `minimum_amount` - Minimum amount supported by this payout method for the indicated currency. Decimal number.\n* `payout_currency` - Currency of the payout. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "object", "fields": [ { "name": "maximum_amount", "type": [ { "type": "unknown" } ] }, { "name": "minimum_amount", "type": [ { "type": "unknown" } ] }, { "name": "payout_currency", "type": [ { "type": "unknown" } ] } ] } ], "required": true }, { "name": "batch_file_header", "description": "Contains a comma-separated list of the headers required for creating a batch file. Relevant for creating a mass payout through the Client Portal.", "type": [ { "type": "string" } ], "required": true }, { "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "type": [ { "type": "string" } ], "name": "beneficiary_country", "required": true }, { "description": "Filters the type of entity for the beneficiary. One of the following:\n* **company**\n* **individual**\n\nRelevant to [List Payout Method Types](ref:list-payout-method-types).", "name": "beneficiary_entity_type", "type": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ], "required": true }, { "name": "beneficiary_entity_types", "description": "A list of the beneficiary entity types supported by this payout method. One or more of the following:\n* **company**\n* **individual**", "type": [ { "type": "array", "arrayTypes": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ] } ], "required": true }, { "name": "beneficiary_required_fields", "description": "Describes the fields required for the beneficiary when you create a payout. Two or more of the following:\n* `name` - Name of the field.\n* `regex` - A regular expression that defines the valid values for the field.\n* `type` - Type of data for the field.\n* `description` - Text description of the field.", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "required": true }, { "name": "category", "description": "The category of payout method type. One of the following:\n* **bank**\n* **card**\n* **cash**\n* ** ewallet** - non-Rapyd eWallet\n* **rapyd_ewallet** - Rapyd wallet", "type": [ { "type": "string", "possibleValues": [ "bank", "card", "cash", "ewallet", "rapyd_ewallet" ] } ], "required": true }, { "name": "ending_before", "description": "ID of the payout object after the last one in the list. String starting with **payout_**.", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": true }, { "name": "identifier_type", "type": [ { "type": "string" } ], "description": "Indicates the type of the bank ID number. Possible values:\n \\* **bic**\n \\* **bicswift**\n \\* Country-specific types with the two-letter country abbreviation as a suffix. For example, **bic_tw**.\n\nRequired when `payout_method_type` is not used.", "required": true }, { "name": "identifier_value", "type": [ { "type": "number" } ], "description": "The bank ID number. Required when `payout_method_type` is not used.", "required": true }, { "description": "URL of an image that the merchant can use to represent the payout method.", "name": "image", "type": [ { "type": "string" } ], "required": true }, { "name": "is_cancelable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout can be canceled. Relevant when `category` is **cash**.", "required": true }, { "name": "is_expirable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout expires if not completed. Relevant when `category` is **cash**.", "required": true }, { "name": "is_location_specific", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout must be made at a specific physical location. Relevant when `category` is **cash**.", "required": true }, { "name": "is_online", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout is made automatically, without any action by the beneficiary.", "required": true }, { "description": "Maximum number of payout object IDs to return. Integer.", "name": "limit", "type": [ { "type": "number" } ], "required": true }, { "name": "maximum_amount", "description": "Maximum amount supported by this payout method for the indicated currency. Decimal number.", "type": [ { "type": "number" } ], "required": true }, { "name": "maximum_expiration_seconds", "type": [ { "type": "number" } ], "description": "The maximum time (in seconds) that the merchant can set for completing the payout. Relevant when `is_expirable` is **true**.", "required": true }, { "description": "A JSON object defined by the client.", "type": [ { "type": "object" } ], "name": "metadata", "required": true }, { "name": "minimum_amount", "description": "Minimum amount supported by this payout method for the indicated currency. Decimal number.", "type": [ { "type": "number" } ], "required": true }, { "description": "The minimum time (in seconds) that the merchant can set for completing the payout. Relevant when `is_expirable` is **true**.", "name": "minimum_expiration_seconds", "type": [ { "type": "number" } ], "required": true }, { "name": "name", "type": [ { "type": "string" } ], "description": "Payout method name.", "required": true }, { "name": "payout_amount", "type": [ { "type": "number" } ], "description": "Amount of the payout, in units of the currency defined in `payout_currency`. Mandatory when `sender_amount` is not used. Decimal.", "required": true }, { "name": "payout_currency", "type": [ { "type": "string" } ], "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "payout_currencies", "description": "A list of the currencies supported by this payout method. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "required": true }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "description": "The type of payout method. Required when `identifier_type` and `default_payout_method_type` are not used.", "required": true }, { "name": "sender_country", "type": [ { "type": "string" } ], "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "sender_currency", "type": [ { "type": "string" } ], "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "sender_currencies", "description": "List of currencies that the sender is paying with. Currency consists of a three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "object" } ], "required": true }, { "name": "sender_entity_type", "description": "Filters the type of entity for the sender. One of the following:\n* **company**\n* **individual**\n\nRelevant to [List Payout Method Types](ref:list-payout-method-types).", "type": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ], "required": true }, { "description": "A list of the sender entity types supported by this payout method. One or more of the following:\n* **company**\n* **individual**", "type": [ { "type": "array", "arrayTypes": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ] } ], "name": "sender_entity_types", "required": true }, { "name": "sender_required_fields", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "Describes the fields required for the sender when you create a payout. Two or more of the following:\n* `name` - Name of the field.\n* `regex` - A regular expression that defines the valid values for the field.\n* `type` - Type of data for the field.\n* `description` - Text description of the field.", "required": true }, { "description": "ID of the payout object before the first one in the list. String starting with **payout_**.", "name": "starting_after", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": true }, { "description": "Indicates whether the payout method is currently available. One of the following values:\n* **0** - Not available.\n* **1** - Available.\n\nRelevant to [List Payout Method Types](ref:list-payout-method-types).", "name": "status", "type": [ { "type": "boolean" } ], "required": true } ] }, { "product": "disburse", "parent": "payout-method-type-object", "id": "list-payout-method-types", "type": "request", "name": "ListPayoutMethodTypesRequest", "description": "Use GET to list payout method types that you can use when creating a payout. The response contains a list of objects. Each object includes a payout method type and its attributes.\nNote: This method should not be used when you intend to use `identifier_type` and `identifier_value` in [Create Payout](ref:create-payout).\n\nYou can also use the Client Portal. Navigate to **My Account > Settings > Payout Methods**.", "method": "GET", "path": "/v1/payouts/supported_types", "params": [], "body": [], "headers": [], "query": [ { "name": "beneficiary_country", "type": [ { "type": "string" } ], "required": false, "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "beneficiary_entity_type", "type": [ { "type": "string" } ], "required": false, "description": "Filters the type of entity for the beneficiary. One of the following: **individual**, **company**" }, { "name": "category", "type": [ { "type": "string" } ], "required": false, "description": "The category of payout method. One of the following: **bank**, **card**, **cash**, **rapyd_ewallet**, **ewallet**" }, { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The name of a payout method in the list. The list ends with the last record that was created before the record with this payout method. Use this filter to get the previous page of results." }, { "name": "is_cancelable", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the payout can be canceled. Relevant when `category` is **cash**." }, { "name": "is_expirable", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the payout expires if not completed. Relevant when `category` is **cash**." }, { "name": "is_location_specific", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the payout must be made at a specific physical location. Relevant when `category` is **cash**." }, { "name": "is_online", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the payout is made automatically, without any action by the beneficiary. Relevant when `category` is **bank**." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of payout methods to return. Range: 1-100. Default is 10." }, { "name": "payout_currency", "type": [ { "type": "string" } ], "required": false, "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase." }, { "name": "sender_entity_type", "type": [ { "type": "string" } ], "required": false, "description": "Filters the type of entity for the payer. One of the following: **individual**, **company**" }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The name of a payout method in the list. The list begins with the record that was created next after the record with this payout method. Use this filter to get the next page of results. Relevant when `ending_before` is not used." } ] }, { "product": "disburse", "parent": "payout-method-type-object", "id": "get-payout-required-fields", "type": "request", "name": "GetPayoutRequiredFieldsRequest", "description": "Use GET to retrieve the fields required to use a payout method type. The fields are returned as a list of objects. The name of each field appears in the `name` field of each object. Use this information for [Create Payout](ref:create-payout), [Create Beneficiary](ref:create-beneficiary) and [Create Sender](ref:create-sender).\n> **Note:** The fields returned by this method are required when you create a payout. If you create a payout with a sender or beneficiary that was created previously, you are responsible for choosing a sender and beneficiary that have all the fields required by the payout method.", "method": "GET", "path": "/v1/payouts/{payout_method_type}/details", "params": [ { "name": "payout_method_type", "type": [ { "type": "string" } ], "required": true, "description": "The type of the payout method. Set to the name of a payout method listed in the response to [List Payout Method Types](ref:list-payout-method-types)." } ], "body": [], "headers": [], "query": [ { "name": "beneficiary_country", "type": [ { "type": "string" } ], "required": true, "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "beneficiary_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the beneficiary. One of the following: **individual**, **company**" }, { "name": "identifier_type", "type": [ { "type": "string" } ], "required": false, "description": "The identifier code of the bank. Required when ‘payout_method_type’ is not used." }, { "name": "identifier_value", "type": [ { "type": "string" } ], "required": false, "description": "The identifier value for the code of the bank entered in `identifier_type`. Required when ‘payout_method_type’ is not used." }, { "name": "payout_amount", "type": [ { "type": "number" } ], "required": true, "description": "Amount of the payout, in units of the currency that the beneficiary is receiving. Decimal." }, { "name": "payout_currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase." }, { "name": "sender_country", "type": [ { "type": "string" } ], "required": true, "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "sender_currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase." }, { "name": "sender_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the sender. One of the following: **individual**, **company**" } ] }, { "product": "collect", "id": "refund-object", "type": "type", "name": "Refund", "description": "The Refund object describes a single refund that is credited against a specific Payment object. You can create a refund when the payment is closed. There is no limit on the number of refunds, and the amount can exceed the amount of the payment. The money is returned to the payment method that was used to make the payment.\n\nTo refund a payment where the funds are collected from two or more payment methods, see [Create Group Refund](ref:create-group-refund).", "fields": [ { "description": "ID of the Refund object. String starting with **refund_**.", "type": [ { "type": "string", "startsWith": "refund_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the refund, in units defined by `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.\n\nIf this parameter is omitted in the 'Create Refund' request, the refund is for the entire remaining amount of the 'payment' object. For more information, see ***Create Refund - Request Parameters*** below.", "required": true }, { "name": "balance_transaction", "type": [ { "type": "string" } ], "description": "The unrefunded amount remaining on the payment. Response only.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of this refund, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the `amount` parameter. Response only.", "required": true }, { "description": "An array of one or more objects that represent wallets that the refund is charged to. Each object contains the following fields:\n* `ewallet` - The ID of the wallet, a string starting with **ewallet_**. Required.\n* `amount` - The amount of the refund charged to this wallet. Decimal. Required when `percentage` is not used.\n* `percent` - The percentage of the refund charged to this wallet. Decimal between 0 and 100. Required when `amount` is not used.\n\n**Note:** All wallets must specify `amount` or all wallets must specify `percentage`.\n\nFor more information, see ***Create Refund - Request Parameters*** below.", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "fields": [ { "name": "ewallet", "type": [ { "type": "unknown" } ] }, { "name": "amount", "type": [ { "type": "unknown" } ] }, { "name": "percent", "type": [ { "type": "unknown" } ] } ] } ] } ], "name": "ewallets", "required": true }, { "name": "failure_reason", "type": [ { "type": "string", "possibleValues": [ "lost_or_stolen_card", "expired_or_canceled_card", "unknown" ] } ], "description": "Indicates the reason that the refund failed. One of the following:\n* **lost_or_stolen_card**\n* **expired_or_canceled_card**\n* **unknown**\n\nResponse only.", "required": true }, { "name": "fixed_side", "type": [ { "type": "string" } ], "description": "Indicates whether the FX rate is fixed for the buy side or for the sell side. Relevant for refunds with foreign exchange. Response only.", "required": true }, { "name": "fx_rate", "type": [ { "type": "string" } ], "description": "Exchange rate for the transaction. When `fixed_side` is **buy**, `fx_rate` is the buy rate. When `fixed_side` is **sell**, `fx_rate` is the sell rate.\nDecimal number as string. \nRelevant to refunds with foreign exchange. Response only.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "Merchant-defined ID. Limited to 255 characters.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "merchant_debited_amount", "type": [ { "type": "string" } ], "description": "Amount debited from the merchant. Relevant to refunds with foreign exchange. Response only.", "required": true }, { "name": "merchant_debited_currency", "type": [ { "type": "string" } ], "description": "Indicates the currency that is debited from the merchant. Three-letter ISO 4217 code. Relevant to refunds with foreign exchange. Response only.", "required": true }, { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "description": "ID of the Payment object that the refund is credited against.\nString starting with **payment_**.\n\nFor more information, see [Payment Object](ref:payment-object).", "required": true }, { "name": "payment_created_at", "type": [ { "type": "number" } ], "description": "Time that the original payment was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "description": "The original payment payment method type. Use [List Payment Methods by Country](ref:list-payment-methods-by-country) for a list of supported types for a country", "required": true }, { "name": "proportional_refund", "type": [ { "type": "boolean" } ], "description": "Indicates whether the refund was returned in proportion to the amounts received by the wallets in the payment. Relevant to a refund for a payment split among multiple wallets.", "required": true }, { "name": "reason", "type": [ { "type": "string" } ], "description": "Description of the reason for the refund, provided by the merchant.", "required": true }, { "name": "receipt_number", "type": [ { "type": "string" } ], "description": "Number of the receipt for the refund, provided by the merchant. Response only.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "Completed", "Rejected", "Pending" ] } ], "description": "Indicates the status of the refund operation. One of the following values:\n* **Completed** - The refund was complete.\n* **Rejected** - The refund was not made because of an internal error.\n* **Pending** - The request created a refund object on the Rapyd platform, but the refund is not yet complete. For example, the refund is for a payment method that requires a customer action, such as cash, bank redirect or bank transfer.\n\nRead-only.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Time that this refund was last updated, in [*Unix time*](ref:glossary). Response only.", "required": true } ] }, { "product": "collect", "parent": "refund-object", "id": "create-refund", "type": "request", "name": "CreateRefundRequest", "description": "Use the POST method to create a refund. The refund is credited against a specific payment. The money is returned to the payment method that was used for the payment, and the currency is the same as what was used in the payment.\n\nIf the action of a third party is not required, this method triggers the **Refund Completed** webhook. This webhook contains the same information as the response.\n\nThe following asynchronous webhook provides information about later changes to the Refund object:\n* [Webhook - Refund Completed](ref:webhook-refund-completed) \n\n**Notes:** \n >* The payment must be in 'closed' status.\n >* If you are running this method in the sandbox and the payment method requires the action of a third party, to complete your refund simulation you must run [Complete Refund](ref:complete-refund).\n >* To refund a payment where the funds are collected from two or more payment methods, see [Create Group Refund](ref:create-group-refund).\n >* Only clients with [PCI](ref:glossary) certification can make a payout to a card.\n >* Some payment methods do not support refunds.\n >* To create a refund from one wallet and not others, include only that wallet in the 'ewallets' array. Do not set `amount` or `percent` to 0.", "method": "POST", "path": "/v1/refunds", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the refund. Decimal. For more information, see [Refund Object](ref:refund-object)." }, { "name": "ewallets", "type": [ { "type": "string" } ], "required": false, "description": "An array of objects that represent wallets that the refund is charged to. For more information, see [Refund Object](ref:refund-object)." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "ID defined by the client. Limited to 255 characters." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the Payment object that the refund is charged against. String starting with **payment_**." }, { "name": "reason", "type": [ { "type": "string" } ], "required": false, "description": "Description of the reason for the refund." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "refund-object", "id": "update-refund", "type": "request", "name": "UpdateRefundRequest", "description": "Use the POST method to change or modify the metadata in a 'refund' object.\n\nThis method triggers the **Refund Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/refunds/{refund}", "params": [ { "name": "refund", "type": [ { "type": "string", "startsWith": "refund_" } ], "required": true, "description": "ID of the 'refund' object you want to update. String starting with **refund_**." } ], "body": [ { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "refund-object", "id": "complete-refund", "type": "request", "name": "CompleteRefundRequest", "description": "Use the POST method to complete a refund. Use this method when a payment was made with a payment method such as cash, bank redirect or bank transfer, and the payment was completed by an action taken by the customer.\n\nUse this method in the sandbox to simulate the action of a third party that is required for completing the refund process.\n\nThis method triggers the **REFUND_COMPLETED** webhook. See [Webhook - Refund Completed](ref:webhook-refund-completed).\n\n**Note:** The path for this method is different from the path for other methods involving refunds.\n\n**Prerequisites:**\n* [Create Payment](ref:create-payment) \n* [Complete Payment](ref:complete-payment), if the payment is not closed by the payment method you chose when you created the payment.\n* [Create Refund](ref:create-refund)", "method": "POST", "path": "/v1/refunds/complete", "params": [], "body": [ { "name": "token", "type": [ { "type": "string", "startsWith": "refund_" } ], "required": true, "description": "ID of the refund. String starting with **refund_**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "refund-object", "id": "retrieve-refund", "type": "request", "name": "RetrieveRefundRequest", "description": "Use the GET method to retrieve the details of a 'refund' object.", "method": "GET", "path": "/v1/refunds/{refund}", "params": [ { "name": "refund", "type": [ { "type": "string", "startsWith": "refund_" } ], "required": true, "description": "ID of the 'refund' object you want to retrieve. String starting with **refund_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "refund-object", "id": "list-refunds", "type": "request", "name": "ListRefundsRequest", "description": "Use the GET method to retrieve a list of all refunds.", "method": "GET", "path": "/v1/refunds", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string", "startsWith": "refund_" } ], "required": false, "description": "The ID of the refund created after the last refund you want to retrieve. String starting with **refund_**." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of refunds to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "refund_" } ], "required": false, "description": "The ID of the refund created before the first refund you want to retrieve. String starting with **refund_**." } ] }, { "product": "collect", "parent": "refund-object", "id": "list-refunds-by-payment-id", "type": "request", "name": "ListRefundsByPaymentIDRequest", "description": "Use the GET method to retrieve a list of 'refund' objects for a specified payment.", "method": "GET", "path": "/v1/refunds", "params": [], "body": [], "headers": [], "query": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." } ] }, { "product": "collect", "parent": "refund-object", "id": "refund-errors", "type": "enum", "name": "RefundError", "values": [ { "name": "ERROR_ADDING_REFUND", "description": "The request tried to create a refund, but the payment was not found. The request was rejected. Corrective action: Use the ID of a valid payment that is in 'closed' status." }, { "name": "ERROR_CREATE_REFUND", "description": "The request tried to create a refund against a payment, but the operation failed. Corrective action: Verify that the payment exists and is not closed, and check all input parameters." }, { "name": "ERROR_CREATE_REFUND_CURRENCY_NOT_VALID", "description": "The request tried to create a refund, but the currency was not recognized. The request was rejected. Corrective action: Set 'currency' to the value of 'merchant_requested_currency' or 'currency_code' from the response to 'Create Payment'." }, { "name": "ERROR_CREATE_REFUND_DUPLICATE_EWALLET", "description": "The request tried to refund a split payment, but the refund split was not defined correctly. The request was rejected. Corrective action: In the ‘ewallets’ array, specify the ‘amount’ field for all wallets or the ‘percent’ field for all wallets." }, { "name": "ERROR_CREATE_REFUND_EWALLET_NOT_FOUND_IN_PAYMENT", "description": "The request tried to refund a payment, but the wallet was not found in the payment. The request was rejected. Corrective action: In the ‘ewallets’ array, specify wallets that appear in the payment." }, { "name": "ERROR_CREATE_REFUND_INVALID_EWALLETS_AMOUNT", "description": "The request tried to create a refund, but the amount from one wallet was not valid. The request was rejected. Corrective action: In the ‘ewallets’ array, set the ‘amount’ field for all wallets to a positive decimal number." }, { "name": "ERROR_CREATE_REFUND_INVALID_EWALLETS_PERCENTAGE", "description": "The request tried to create a refund, but the percentage from one wallet was not valid. The request was rejected. Corrective action: In the ‘ewallets’ array, set the ‘percentage’ field for all wallets to a decimal number between 0 and 100." }, { "name": "ERROR_CREATE_REFUND_MISSING_EWALLET_ID", "description": "The request tried to refund a payment, but the ID of one of the wallets was missing. The request was rejected. Corrective action: In the 'ewallet' field, provide the ID of the wallet that the refund will be taken from." }, { "name": "ERROR_CREATE_REFUND_PAYMENT_NOT_REFUNDABLE", "description": "The request tried to create a refund, but the payment method does not allow this operation. The request was rejected. Corrective action: Send the funds to the payer using ‘Create Payout’ or ‘Transfer Funds Between Wallets’, or contact Client Support." }, { "name": "ERROR_GET_EWALLET_NOT_ENOUGH_FUNDS", "description": "The request tried to create a refund of a payment to one or more wallets, but one of the wallets did not have enough funds to complete the refund. The request was rejected. Corrective action: Fund the wallet with 'Create Payment' or transfer funds from another wallet using 'Transfer Funds Between Wallets'." }, { "name": "ERROR_UPDATE_REFUND", "description": "The request tried to update a refund, but the refund was not found, or the operation failed. The request was rejected. Corrective action: Check all input fields, and verify that the refund exists and was not already closed." }, { "name": "INVALID_REFUND", "description": "The request attempted an operation that requires a refund, but the refund was not found. The request was rejected. Corrective action: Use the ID of a valid refund." }, { "name": "INVALID_REFUND_STATUS", "description": "The request tried to complete a refund, but the refund was already completed and closed. The request was rejected. Corrective action: Determine why multiple attempts were made to complete the same refund." }, { "name": "INVALID_REFUND_TOKEN", "description": "The request tried to update a refund, but the refund was not found. The request was rejected. Corrective action: Use the ID of a valid refund." }, { "name": "PAYMENT_NOT_COMPLETED", "description": "The request tried to create a refund, but the payment object on which the refund is based is not in 'closed' status. The request was rejected. Corrective action: Wait until the payment is closed, and then create the refund." } ] }, { "product": "issuing", "id": "rapyd-authorization-object", "type": "type", "name": "RapydAuthorization", "description": "The Rapyd Authorization Object holds information about authorization services for transactions on issued cards, including completed sale, adjustment and reversal.", "fields": [ { "description": "* ID of the authorization. String starting with **cardauth_**. Relevant to simulations.\n\n* ID of the issued card transaction object. String starting with **cit_**. Response only. Relevant to webhooks.", "type": [ { "type": "string", "startsWith": "cardauth_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the transaction, in units defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.", "required": true }, { "name": "auth_code", "type": [ { "type": "string" } ], "description": "Authorization code sent to the merchant. Response only.", "required": true }, { "name": "auth_response", "type": [ { "type": "object", "fields": [ { "name": "code", "type": [ { "type": "unknown" } ] }, { "name": "message", "type": [ { "type": "unknown" } ] } ] } ], "description": "Response related to an authorization. Contains the following fields: \n\\* `code` - Indicates success or reason for failure. \n\\* `message` - Descriptive text.\n\nResponse only.", "required": true }, { "name": "bin", "type": [ { "type": "string" } ], "description": "The first 6 digits of the card number. Response only.", "required": true }, { "type": [ { "type": "string", "startsWith": "card_" } ], "name": "card_id", "description": "ID of the card. String starting with **card_**.", "required": true }, { "name": "card_program", "type": [ { "type": "string", "startsWith": "cardprog_" } ], "description": "ID of the card program that the card is issued from. String starting with **cardprog_**. Response only.", "required": true }, { "name": "card_transaction_id", "type": [ { "type": "string", "startsWith": "cit_" } ], "description": "ID of the transaction. String starting with **cit_**. Response only.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the transaction object, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Currency of the transaction. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "Currency of the transaction. Three-letter ISO 4217 code. Uppercase. Response only.", "required": true }, { "name": "financial_impact", "type": [ { "type": "string", "possibleValues": [ "credit", "debit" ] } ], "description": "The financial impact of an adjustment. One of the following: \n\\* **credit**\n\\* **debit**", "required": true }, { "name": "fx_rate", "description": "The exchange rate. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "is_remote_auth", "description": "Indicates whether remote authorization is enabled. Response only.", "type": [ { "type": "boolean" } ], "required": true }, { "name": "issuing_txn_type", "type": [ { "type": "string", "possibleValues": [ "sale", "reversal", "adjustment", "refund" ] } ], "description": "Type of the transaction. One of the following:\n\\* **sale**\n\\* **reversal**\n\\* **adjustment**\n\\* **refund**\n\nResponse only.", "required": true }, { "name": "last4", "description": "The last 4 digits of the card number. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "merchant_category_code", "type": [ { "type": "string" } ], "description": "Four-digit merchant category code (MCC) of the initiator of the transaction, as defined in [ISO 18245](https://www.iso.org/standard/33365.html).", "required": true }, { "name": "merchant_identification_code", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "merchant_name_location", "type": [ { "type": "string" } ], "description": "Name and location of the merchant. Maximum 40 characters. Default is 'TEST MERCHANT'.", "required": true }, { "name": "original_transaction_id", "type": [ { "type": "string", "startsWith": "cit_" } ], "description": "ID of the original issued card transaction. String starting with **cit_**. Response only.", "required": true }, { "name": "original_txn_amount", "type": [ { "type": "number" } ], "description": "Original amount for FX transactions, when `currency` is different from `original_txn_currency`. Response only.", "required": true }, { "name": "original_txn_currency", "description": "Original currency in FX transaction. Three-letter ISO 4217 code. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "pos_entry_mode", "description": "The mode of the POS entry. One of the following:\n\\* **magstripe**\n\\* **manual_entered**\n\\* **emv**\n\\* **emv_standin**\n\\* **nfc**\n\\* **network_token**\n\\* **ecommerce**\n\\* **3ds_ecommerce**\n\\* **adjustment**\n\nResponse only.", "type": [ { "type": "string", "possibleValues": [ "magstripe", "manual_entered", "emv", "emv_standin", "nfc", "network_token", "ecommerce", "3ds_ecommerce", "adjustment" ] } ], "required": true }, { "name": "remote_auth_endpoint", "type": [ { "type": "string" } ], "description": "The URL where the remote authorization is sent. Response only.", "required": true }, { "name": "remote_auth_response", "type": [ { "type": "object", "fields": [ { "name": "authorization_id", "type": [ { "type": "unknown" } ] }, { "name": "response_code", "type": [ { "type": "unknown" } ] }, { "name": "auth_code", "type": [ { "type": "unknown" } ] } ] } ], "description": "Response to a successful remote authorization request. Contains the following fields: \n\\* `authorization_id` - ID of the authorization. String starting with **cardauth_**. \n\\* `response_code` - Code returned by the client in the response to the remote authorization. \n\\* `auth_code` - Authorization code returned by the client in the response to the remote authorization. \n\nResponse only.", "required": true }, { "name": "retrieval_reference_number", "description": "Retrieval reference number for a card transaction. Appears in the response to [List Issued Card Transactions](ref:list-issued-card-transactions). Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "systems_trace_audit_number", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "transaction_amount", "type": [ { "type": "number" } ], "description": "Amount debited from the Rapyd Wallet. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Response only.", "required": true }, { "name": "transaction_currency_code", "type": [ { "type": "string" } ], "description": "Original transaction currency, if different from the currency credited to the Rapyd Wallet. Three-letter ISO 4217 code. Uppercase. Response only.", "required": true }, { "name": "wallet_transaction_id", "type": [ { "type": "string", "startsWith": "wt_" } ], "description": "ID of the wallet transaction. String starting with **wt_**. Response only.", "required": true } ] }, { "product": "issuing", "parent": "rapyd-authorization-object", "id": "simulate-a-card-adjustment", "type": "request", "name": "SimulateACardAdjustmentRequest", "description": "A retail location can adjust the amount of a transaction made by an issued card. The adjustment is either a credit or a debit. \n\nUse this method in the sandbox to simulate an adjustment.\n\nThis method triggers [Webhook - Card Issuing Adjustment](ref:webhook-card-issuing-adjustment).\n\n**Prerequisites:**\n \\* [Issue Card](ref:issue-card)\n \\* [Activate Issued Card](ref:activate-issued-card)\n \\* [Simulate a Card Authorization Request](ref:simulate-a-card-authorization-request)", "method": "POST", "path": "/v1/issuing/cards/adjustment", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the adjustment, in units of the currency defined in `currency`. Decimal." }, { "name": "card_id", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the card. String starting with **card_**." }, { "name": "card_transaction_id", "type": [ { "type": "string", "startsWith": "cit_" } ], "required": true, "description": "ID of the transaction to adjust. String starting with **cit_**." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "The adjustment currency. Three-letter ISO 4217 code. Uppercase." }, { "name": "financial_impact", "type": [ { "type": "string" } ], "required": true, "description": "Indicates the financial impact of the adjustment. One of the following: **credit**, **debit**." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "rapyd-authorization-object", "id": "simulate-a-card-refund", "type": "request", "name": "SimulateACardRefundRequest", "description": "A retail location can make a refund to an issued card.\n\nUse this method in the sandbox to simulate a refund.\n\nThis method triggers the **CARD_ISSUING_REFUND** webhook. See [Webhook - Card Issuing Refund](ref:webhook-card-issuing-refund).\n\n**Prerequisites:**\n \\* [Issue Card](ref:issue-card)\n \\* [Activate Issued Card](ref:activate-issued-card)", "method": "POST", "path": "/v1/issuing/cards/refund", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the refund, in units of the currency defined in `currency`. Decimal." }, { "name": "card_id", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the card. String starting with **card_**." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "The refund currency. Three-letter ISO 4217 code. Uppercase." }, { "name": "merchant_category_code", "type": [ { "type": "string" } ], "required": false, "description": "Four-digit merchant category code (MCC) of the initiator of the refund, as defined in [ISO 18245](https://www.iso.org/standard/33365.html)." }, { "name": "merchant_name_location", "type": [ { "type": "string" } ], "required": false, "description": "The name and location of the merchant that initiates the refund." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "rapyd-authorization-object", "id": "rapyd-authorization-errors", "type": "enum", "name": "RapydAuthorizationError", "values": [ { "name": "ERROR_AUTHORIZATION_INVALID_AMOUNT", "description": "The request tried to simulate an authorization operation on a card transaction, but the amount was not valid. The request was rejected. Corrective action: Set 'amount' to a positive decimal number." }, { "name": "ERROR_AUTHORIZATION_INVALID_CURRENCY", "description": "The request tried to simulate an authorization operation on a card transaction, but the currency was not valid. The request was rejected. Corrective action: Set 'currency' to a 3-letter ISO 4217 code." }, { "name": "ERROR_AUTHORIZATION_MISSING_AMOUNT", "description": "The request tried to simulate an authorization operation on a card transaction, but the amount was not found. The request was rejected. Corrective action: Set 'amount' to a positive decimal number." }, { "name": "ERROR_AUTHORIZATION_MISSING_CARD_ID", "description": "The request tried to simulate an authorization operation on a card transaction, but the card was not found. The request was rejected. Corrective action: Set 'card_id' to the card ID, a string starting with 'card’." }, { "name": "ERROR_AUTHORIZATION_MISSING_CARD_TRANSACTION_ID", "description": "The request tried to simulate an authorization operation on a card transaction, but the transaction was not found. The request was rejected. Corrective action: Set 'card_transaction_id' to the ID of the transaction, a string starting with 'cit’." }, { "name": "ERROR_AUTHORIZATION_MISSING_CURRENCY", "description": "The request tried to simulate an authorization operation on a card transaction, but the currency was not found. The request was rejected. Corrective action: Set 'currency' to a 3-letter ISO 4217 code." }, { "name": "ERROR_AUTHORIZATION_MISSING_FINANCIAL_IMPACT", "description": "The request tried to simulate an authorization operation on a card transaction, but the financial impact was not found. The request was rejected. Corrective action: Set 'financial_impact' to 'credit' or 'debit'." } ] }, { "product": "collect", "id": "usage-record-object", "type": "type", "name": "UsageRecord", "description": "A usage record indicates the quantity for a subscription item whose plan is based on metered billing. A subscription item has one or more usage records.\nSee also [Plan Object](ref:plan-object).", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "subiur_" } ], "description": "ID of the Usage Record object. String starting with **subiur_**.", "required": true }, { "name": "action", "description": "Determines `quantity` for the usage record. One of the following values:\n* **increment** - Adds the quantity to the cumulative `quantity` of the usage record. This is the default.\n* **set** - Replaces the `quantity` of the usage record.\n\n**Note:** `action` has no impact when a new usage record is created. It is used to update an existing usage record where its unique identifier is composed of `timestamp` and `subscription_ item`.", "type": [ { "type": "string", "possibleValues": [ "increment", "set" ] } ], "required": true }, { "name": "ending_before", "description": "A filtering field for the latest date and time of the returned usage records. Format is in [*Unix time*](ref:glossary).", "type": [ { "type": "number" } ], "required": true }, { "name": "limit", "description": "A filtering field for the maximum number of usage records that are returned. Default is 10.", "type": [ { "type": "number" } ], "required": true }, { "name": "quantity", "type": [ { "type": "number" } ], "description": "The number of units of the service that the customer is billed for. See also [Plan Object](ref:plan-object).", "required": true }, { "name": "starting_after", "description": "A filtering field for the earliest date and time of the returned usage records. Format is in [*Unix time*](ref:glossary).", "type": [ { "type": "number" } ], "required": true }, { "name": "subscription_item", "type": [ { "type": "string" } ], "description": "The ID of subscription item that the usage record belongs to. String starting with **subi\\_**.", "required": true }, { "name": "timestamp", "type": [ { "type": "number" } ], "description": "Timestamp for the usage record in [*Unix time*](ref:glossary).", "required": true } ] }, { "product": "collect", "parent": "usage-record-object", "id": "create-usage-record", "type": "request", "name": "CreateUsageRecordRequest", "description": "Use the POST method to create a usage record or update an existing usage record where its unique identifier is composed of `timestamp` and `subscription_item`.", "method": "POST", "path": "/v1/subscription_items/{subscription_item}/usage_records", "params": [ { "name": "subscription_item", "type": [ { "type": "string", "startsWith": "subi_" } ], "required": true, "description": "ID of the subscription item. String starting with **subi_**." } ], "body": [ { "name": "quantity", "type": [ { "type": "number" } ], "required": true, "description": "The usage quantity for the specified date and time (timestamp)." }, { "name": "timestamp", "type": [ { "type": "number" } ], "required": true, "description": "Timestamp for the usage record in [*Unix time*](ref:glossary)." }, { "name": "action", "type": [ { "type": "string" } ], "required": false, "description": "Determines how the quantity is defined in the usage record." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "usage-record-object", "id": "list-usage-records", "type": "request", "name": "ListUsageRecordsRequest", "description": "Use the GET method to retrieve a list of usage records for a subscription item.", "method": "GET", "path": "/v1/subscription_items/{subscription_item}/usage_record_summaries", "params": [ { "name": "subscription_item", "type": [ { "type": "string", "startsWith": "subi_" } ], "required": true, "description": "ID of the subscription item. String starting with **subi_**." } ], "body": [], "headers": [], "query": [ { "name": "limit", "type": [ { "type": "number" } ], "required": false, "description": "The maximum number of usage records that are returned. Range: 1-100. Default is 10." }, { "name": "ending_before", "type": [ { "type": "number" } ], "required": false, "description": "The latest date and time of the returned usage records. Format is in [*Unix time*](ref:glossary)." }, { "name": "starting_after", "type": [ { "type": "number" } ], "required": false, "description": "The earliest date and time of the returned usage records. Format is in [*Unix time*](ref:glossary)." } ] }, { "product": "collect", "parent": "usage-record-object", "id": "usage-record-errors", "type": "enum", "name": "UsageRecordError", "values": [ { "name": "ERROR_DELETE_SUBSCRIPTION_ITEM_USAGE_RECORD", "description": "The request tried to delete a subscription usage record, but the operation failed. Corrective action: Determine whether the subscription usage record was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_UPDATE_USAGE_RECORDS", "description": "The request tried to update subscriptions usage records. The request was rejected." }, { "name": "ERROR_USAGE_RECORD_ACTION_NOT_VALID", "description": "The request tried to create a usage record, but the action was not recognized. The request was rejected. Corrective action: Define the 'action' body parameter as 'increment' or 'set'." }, { "name": "ERROR_USAGE_RECORD_TIMESTAMP_NOT_VALID", "description": "The request tried to create a usage record for a subscription item, but the timestamp was not valid. The request was rejected. Corrective action: Provide a valid Unix timestamp for a time in the current billing period for the relevant subscription." }, { "name": "INVALID_GET_USAGE_RECORD_SUMMARIES_ENDING_BEFORE", "description": "The request tried to get a list of usage record summaries, but the query was not valid. The request was rejected. Corrective action: For the 'ending_before' query parameter, use a valid Unix timestamp." }, { "name": "INVALID_GET_USAGE_RECORD_SUMMARIES_LIMIT", "description": "The request tried to get a list of usage record summaries, but the query was not valid. The request was rejected. Corrective action: Set the 'limit' query parameter to an integer between 1 and 100." }, { "name": "INVALID_GET_USAGE_RECORD_SUMMARIES_STARTING_AFTER", "description": "The request tried to get a list of usage record summaries, but the query was not valid. The request was rejected. Corrective action: For the 'starting_after' query parameter, use a valid Unix timestamp." }, { "name": "INVALID_GET_USAGE_RECORD_SUMMARIES_SUBSCRIPTION_ITEM_ID", "description": "The request tried to get a list of usage record summaries, but the relevant subscription item was not found. The request was rejected. Corrective action: Provide the ID of a valid subscription item, which is a string starting with 'subi'." }, { "name": "INVALID_SUBSCRIPTION_ITEM_USAGE_RECORD_QUANTITY", "description": "The request tried to create a usage record, but the quantity was in incorrect format or a negative number. The quantity must be a positive number. The request was rejected. Corrective action: Use a positive number for the quantity." }, { "name": "INVALID_SUBSCRIPTION_ITEM_USAGE_RECORD_TIMESTAMP", "description": "The request tried to create a usage record, but the value for the 'timestamp' body parameter was not in the correct format. The request was rejected. Corrective action: Use a valid Unix timestamp." } ] }, { "product": "collect", "id": "discount-object", "type": "type", "name": "Discount", "description": "", "fields": [ { "name": "id", "type": [ { "type": "string" } ], "description": "ID of the `discount` object in the customer or subscription.", "required": true }, { "name": "coupon", "type": [ { "type": "object", "id": "coupon-object" } ], "description": "See [Coupon Object](ref:coupon-object).", "required": true } ] }, { "product": "disburse", "id": "product-object-disburse", "type": "type", "name": "Product", "description": "The Product object describes a service that can be paid for using a payout subscription.", "fields": [ { "description": "Unique string for identification of the product. Legal input includes alphanumeric characters and the underscore (_) character. If the merchant does not define an ID, Rapyd generates it with a string that starts with **product_**.", "type": [ { "type": "string" } ], "name": "id", "required": true }, { "name": "active", "type": [ { "type": "boolean" } ], "description": "Indicates whether the product is currently available for purchase.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of this product, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Full text description of the product.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "name", "type": [ { "type": "string" } ], "description": "The name of the product or service that appears in the line items in invoices.", "required": true }, { "name": "shippable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the product can be shipped.", "required": true }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "description": "Description that is suitable for a customer's statement. Limited to 22 characters.", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Set to **services**.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Time that this product was last updated, in [*Unix time*](ref:glossary). Response only.", "required": true } ] }, { "product": "collect", "id": "subscription-object-collect", "type": "type", "name": "Subscription", "description": "A subscription defines periodic collection transactions without further input from the client or customer.", "fields": [ { "description": "ID of the Subscription object. String starting with **sub_**.", "type": [ { "type": "string", "startsWith": "sub_" } ], "name": "id", "required": true }, { "name": "billing", "type": [ { "type": "string" } ], "description": "Determines the method of billing at the end of the billing cycle. Set to **pay_automatically** - Rapyd generates a 'payment' object, then attempts to pay it using the designated payment method. \nSee [Invoice Object](ref:invoice-object).", "required": true }, { "name": "billing_cycle_anchor", "type": [ { "type": "string", "possibleValues": [ "now", "unchanged" ] }, { "type": "number" } ], "description": "Determines the start of the next full billing cycle, as defined in the plan described in the 'items'. One of the following values:\n\\* **now** - The present day. The next billing cycle starts right now.\n*Timestamp* in [*Unix time*](ref:glossary) - A time in the future, at or after the end of the free trial period, not more than the length of the billing cycle. The current billing cycle will be shorter than all other billing cycles. Relevant to creation of the subscription.\n\\* **unchanged** - The original billing cycle anchor is unchanged. Relevant to updating a subscription.\n\n**Note:** If you update `trial_end`, this parameter will be reset to the end of the new trial period. If you want a different billing cycle anchor, you must update the subscription again at the moment you want, and set this parameter to **now**.", "required": true }, { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "description": "Determines the last date that charges accrue.\n\n\\* **true** - Charges accrue until the end of the current billing period, then the subscription is canceled.\n\\* **false** \n> * When the subscription is created, no end is defined.\n> * When [Cancel Subscription](ref:cancel-subscription) is run, charges stop immediately and the subscription is canceled.", "required": true }, { "name": "canceled_at", "type": [ { "type": "number" } ], "description": "Date and time that the subscription is canceled by the customer or by the client. [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "coupon", "type": [ { "type": "string" } ], "description": "The ID of a discount coupon that applies to all invoice lines associated with this subscription. If the coupon defines a fixed monetary discount, it must use the same currency as the subscription's plan.\n\nSee also:\n\n** [Coupon Object](ref:coupon-object).\n** [Plan Object](ref:plan-object).", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of this subscription, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "current_period_end", "type": [ { "type": "number" } ], "description": "End of the current billing cycle, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "current_period_start", "type": [ { "type": "number" } ], "description": "Start of the current billing cycle, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer who pays for this subscription. String starting with **cus_**.\nRequired. \n\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "days_until_due", "type": [ { "type": "number" } ], "description": "Number of days between the date of issuance of an invoice and the date payment is due. Integer. Relevant when `billing` is **send_invoice**.", "required": true }, { "name": "discount", "type": [ { "type": "object", "id": "discount-object" } ], "description": "Contains information about the coupon that applies to the subscription. Response only.\n\nAdding a discount is a 2-step process:\n1. [Create Coupon](ref:create-coupon), which returns a coupon ID. \n2. Add the coupon ID to the `coupon` field of the subscription with [Create Subscription](ref:create-subscription-object) or [Update Subscription](ref:update-subscription).\n\nFor more information, see [Discount Object](ref:discount-object).", "required": true }, { "name": "ended_at", "type": [ { "type": "number" } ], "description": "Date that the subscription was canceled or otherwise terminated. [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "payment_fields", "type": [ { "type": "object", "id": "payment-object" } ], "description": "Object containing fields of the Payment object. \n\nFor more information, see [Payment Object](ref:payment-object).", "required": true }, { "name": "payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "Payment method ID or Payment Method object. If not specified in this field, the payment method is the default payment method specified for the customer.\n\nTo create a payment method ID, use the [Add Payment Method](ref:add-payment-method) method. The ID is a string starting with **card_** or **other_**.\n\nFor more information, see [Payment Method Object](#payment-method-object).", "required": true }, { "name": "start", "type": [ { "type": "number" } ], "description": "Date and time that the subscription began, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "active", "canceled", "past_due", "trialing", "unpaid" ] } ], "description": "Status of the subscription. One of the following:\n\\* **active** - The customer is currently paying for this subscription.\n\\* **canceled** - The customer has canceled this subscription, but it remains in the Rapyd database.\n\\* **past_due** - Payment for this subscription was not received by the end of the billing period.\n\\* **trialing** - The subscription is in its free trial period.\n\\* **unpaid** - An error occurred in the payment for this subscription.", "required": true }, { "name": "subscription_items", "type": [ { "type": "object", "fields": [ { "name": "plan", "type": [ { "type": "unknown" } ] }, { "name": "quantity", "type": [ { "type": "unknown" } ] }, { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ] }, { "type": "array" } ], "description": "In requests, an array of objects containing the following fields:\n\\* `plan` - ID of a plan that describes the service and pricing structure. String.\n\\* `quantity` - Number of units of the service described in `plan`.\n\nIn responses, an object containing the following fields:\n\\* `data` - A list of up to three subscription items.\n\\* `has_more` - Indicates whether there are more than three items in this subscription.\n\\* `total_count` - Total number of items in this subscription.\n\\* `url` - URL for requesting all of the items in this subscription.\n\n**NOTE:** All subscription items must have plans with identical values for `interval` and `interval_count`.", "required": true }, { "name": "tax_percent", "type": [ { "type": "number" } ], "description": "The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal.\n\nRange: 0-100, with up to four decimal places.", "required": true }, { "name": "total_count", "type": [ { "type": "number" } ], "description": "Total amount of subscription items that are not displayed.", "required": true }, { "name": "trial_end", "type": [ { "type": "number" } ], "description": "The date and time of the end of the customer's free trial period, in [*Unix time*](ref:glossary), or the string **now**. Takes precedence over `trial_period_days`. If `trial_end` is not set by the client, Rapyd calculates this date by adding `trial_period_days` to the date in `created_at`. Relevant when `trial_period_days` is not defined.", "required": true }, { "name": "trial_from_plan", "type": [ { "type": "boolean" } ], "description": "Determines whether a free trial period can be defined in a 'plan' object attached to the subscription.\n\n\\* **True** - Free trials can be defined in plans that are attached to the subscription. This is the default.\n\\* **False** - Definitions of free trial in plans are ignored.", "required": true }, { "name": "trial_period_days", "type": [ { "type": "number" } ], "description": "The number of days in the customer's free trial period. Integer. Range: 0-730. This value takes precedence over trial periods that are defined in a plan. Relevant when `trial_end` is not defined.", "required": true }, { "name": "trial_start", "type": [ { "type": "number" } ], "description": "Date and time of the start of the customer's free trial period, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "payment", "payout" ] } ], "description": "The type of the subscription. One of the following values:\n\\* **payment**\n\\* **payout**", "required": true } ] }, { "product": "collect", "parent": "subscription-object-collect", "id": "create-subscription", "type": "request", "name": "CreateSubscriptionRequest", "description": "Use the POST method to create a subscription.\n\n> **Note:** Only clients with [PCI](ref:glossary) certification can handle personal identifying information for cards. Clients that are not PCI-certified can use [Rapyd Checkout](doc:rapyd-checkout-overview) to collect money from a card.\n\nThis method triggers the **Customer Subscription Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/payments/subscriptions", "params": [], "body": [ { "name": "billing", "type": [ { "type": "string" } ], "required": true, "description": "Determines the method of billing. Set to **pay_automatically**." }, { "name": "billing_cycle_anchor", "type": [ { "type": "string" } ], "required": false, "description": "Determines the start of the next billing cycle, as defined in the plan described in the 'items'. Value must be timestamp in [*Unix time*](ref:glossary)." }, { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "required": false, "description": "Terminates the subscription at the end of the current billing period. Default is **false**." }, { "name": "coupon", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a discount coupon that applies to all subscription items associated with this subscription. If the coupon defines a fixed monetary discount, it must use the same currency as the subscription's plan." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "ID of the customer who pays for this subscription. String starting with **cus_**. Relevant to payments." }, { "name": "days_until_due", "type": [ { "type": "number" } ], "required": false, "description": "Number of days between the date of issuance of an invoice and the date payment is due." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment_fields", "type": [ { "type": "object" } ], "required": false, "description": "Object containing fields of the 'payment' object." }, { "name": "payment_method", "type": [ { "type": "string" } ], "required": false, "description": "Payment method ID or 'payment_method' object." }, { "name": "subscription_items", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "required": true, "description": "Array of subscription items. Each item contains a plan (required) and a quantity (optional)." }, { "name": "tax_percent", "type": [ { "type": "string" } ], "required": false, "description": "The percentage of tax that is applied to the entire amount of the invoice or periodic billing statement." }, { "name": "trial_end", "type": [ { "type": "number" } ], "required": false, "description": "The time of the end of the customer's free trial period. If `trial_from_plan` is set, leave this parameter unset." }, { "name": "trial_from_plan", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether a free trial period can be defined in a 'plan' object attached to the subscription. If `trial_end` is set, leave this parameter unset." }, { "name": "trial_period_days", "type": [ { "type": "number" } ], "required": false, "description": "The number of days in the customer's free trial period." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "update-subscription", "type": "request", "name": "UpdateSubscriptionRequest", "description": "Use the POST method to change or modify a subscription.\n\nYou can redefine the trial period if the status is **active** or **trialing**. If you change `trial_end` to **now**, the trial period ends immediately and `billing_cycle_anchor` is set to the present time. If you define a new trial period and `prorate` is **true**, the charges will be prorated.\n\nThis method triggers the **Customer Subscription Updated** webhook. This webhook contains the same information as the response.\n\n**Note:** For a payout subscription, only `description` and `metadata` are supported.", "method": "POST", "path": "/v1/payments/subscriptions/{subscription}", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [ { "name": "billing", "type": [ { "type": "string" } ], "required": false, "description": "Determines the method of billing. Set to **pay_automatically**." }, { "name": "billing_cycle_anchor", "type": [ { "type": "string" } ], "required": false, "description": "Resets the start of the next billing cycle to the current day. Value: **now**" }, { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "required": false, "description": "Terminates the subscription at the end of the current billing period." }, { "name": "coupon", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a discount coupon that applies to all subscription items associated with this subscription." }, { "name": "days_until_due", "type": [ { "type": "number" } ], "required": false, "description": "Number of days between the date of issuance of an invoice and the date payment is due." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment_fields", "type": [ { "type": "object" } ], "required": false, "description": "Object containing fields of the 'payment' object." }, { "name": "tax_percent", "type": [ { "type": "number" } ], "required": false, "description": "The percentage of tax that is applied to the entire amount of the invoice or periodic billing statement." }, { "name": "trial_end", "type": [ { "type": "number" } ], "required": false, "description": "The time of the end of the customer's free trial period. If `trial_from_plan` is set, leave this parameter unset." }, { "name": "trial_from_plan", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether a free trial period can be defined in a 'plan' object attached to the subscription. If `trial_end` is set, leave this parameter unset. Default is **true**." }, { "name": "trial_period_days", "type": [ { "type": "number" } ], "required": false, "description": "The number of days in the customer's free trial period." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "complete-a-cycle", "type": "request", "name": "CompleteACycleRequest", "description": "Use the POST method to cancel the subscription and create an invoice.\n\nThis method is for testing purposes and runs only in the sandbox.", "method": "POST", "path": "/v1/subscriptions/{subscription}/complete_cycle", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "start-a-new-cycle", "type": "request", "name": "StartANewCycleRequest", "description": "Use the POST method to end a subscription cycle, create an invoice and move the subscription to the next cycle.\n\nThis method is for testing purposes and runs only in the sandbox.\n\nThis method triggers the **New Cycle Started** webhook.", "method": "POST", "path": "/v1/subscriptions/{subscription}/start_new_cycle", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "retrieve-subscription", "type": "request", "name": "RetrieveSubscriptionRequest", "description": "Use the GET method to retrieve the details of a subscription.", "method": "GET", "path": "/v1/payments/subscriptions/{subscription}", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "list-subscriptions", "type": "request", "name": "ListSubscriptionsRequest", "description": "Use the GET method to retrieve a list of subscriptions. You can filter the list with one or more query parameters.", "method": "GET", "path": "/v1/payments/subscriptions", "params": [], "body": [], "headers": [], "query": [ { "name": "billing", "type": [ { "type": "string" } ], "required": false, "description": "Method of billing. One of the following: **pay_automatically**, **send_invoice**." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "ID of the customer. String starting with **cus_**." }, { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a record in the list. The list ends with the last record that was created before the record with this ID. Use this filter to get the previous page of results." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of subscriptions to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a record in the list. The list begins with the record that was created next after the record with this ID. Use this filter to get the next page of results. Relevant when `ending_before` is not used." }, { "name": "status", "type": [ { "type": "string" } ], "required": false, "description": "Status of the subscription. One of the following: **active**, **canceled**, **trialing**" } ] }, { "product": "collect", "parent": "subscription-object-collect", "id": "cancel-subscription", "type": "request", "name": "CancelSubscriptionRequest", "description": "Use the DELETE method to cancel a subscription. Use the 'at_period_end' parameter to control the date of cancellation:\n> \\* **false** - Cancel immediately. This is the default.\n> \\* **true** - Cancel at the end of the current billing period. For payout subscription, value must be 'true'.\n\nThis method triggers the **Customer Subscription Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/payments/subscriptions/{subscription}", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [ { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "required": false, "description": "Cancels the subscription at the end of the current period. When **false**, cancels the subscription immediately. Default is **false**. Set to **true** when canceling a payout subscription." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "delete-discount-from-subscription", "type": "request", "name": "DeleteDiscountFromSubscriptionRequest", "description": "Use the DELETE method to delete the discount that has been assigned to a subscription. \n\nThis method does not affect the coupon that the discount was derived from.", "method": "DELETE", "path": "/v1/payments/subscriptions/{subscription}/discount", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-object-collect", "id": "subscription-errors", "type": "enum", "name": "SubscriptionError", "values": [ { "name": "ERROR_CANCEL_SUBSCRIPTION", "description": "The request tried to cancel a subscription, but the subscription was not found. The request was rejected. Corrective action: Determine whether the subscription was previously canceled, and check all input parameters." }, { "name": "ERROR_DAYS_UNTIL_DUE_BILLING_INCORRECT", "description": "The request tried to create or update a subscription, but the 'days_until_due' body parameter was set and 'billing' was not set to 'send_invoice'. The request was rejected. Corrective action: Set 'billing' to 'send_invoice'." }, { "name": "ERROR_DELETE_SUBSCRIPTION_DISCOUNT", "description": "The request tried to delete a discount from a subscription, but the operation failed. Corrective action: Determine whether the discount was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_DELETE_SUBSCRIPTION_ITEM", "description": "The request tried to delete a subscription item from a subscription, but the operation failed. Corrective action: Determine whether the subscription item was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_PLANS", "description": "The request tried to create a subscription, but the plan was not found. The request was rejected. Corrective action: In each object in the ‘subscription_items’ array, set 'plan' to the ID of a valid plan." }, { "name": "ERROR_GET_SUBSCRIPTION", "description": "The request attempted an operation that requires a subscription, but the subscription was not found. The request was rejected. Corrective action: Use a valid subscription ID." }, { "name": "ERROR_GET_SUBSCRIPTION_LIST", "description": "The request tried to retrieve a list of subscriptions, but there was an error in the query syntax. The request was rejected. Corrective action: Use the correct names of all query parameters." }, { "name": "ERROR_INVALID_TAX_PERCENT_INPUT", "description": "The request tried to create or update a subscription, but the 'days_until_due' body parameter was set and 'billing' was not set to 'send_invoice'. The request was rejected. Corrective action: Set 'billing' to 'send_invoice'." }, { "name": "ERROR_PAYMENT_METHOD_TYPE_CURRENCY_DOES_NOT_MATCH_PLAN", "description": "The request tried to set a payment method for a subscription, but the payment method does not support the currency in the plan for a subscription item. The request was rejected. Corrective action: Choose a payment method that supports the currency of the subscription item." }, { "name": "ERROR_PLAN_INTERVAL_DOES_NOT_MATCH", "description": "The request tried to add a subscription item based on a plan, but the billing interval for the plan did not match the interval of all the subscription items in the subscription. The request was rejected. Corrective action: Add only plans that have the same 'interval' and 'interval_count' as the subscription items in the subscription." }, { "name": "ERROR_SET_TRIAL_TO_UNPAID_SUBSCRIPTION", "description": "The request tried to add a free trial to an existing subscription, but full payment was not received for the previous billing period. The request was rejected. Corrective action: Add the free trial after the previous billing period is fully paid." }, { "name": "ERROR_SUBSCRIPTION_BILLING_CYCLE_ANCHOR_INCORRECT", "description": "The request tried to create or update a subscription, but the billing cycle anchor was not recognized. The request was rejected. Corrective action: To create a subscription, set the 'billing_cycle_anchor' body parameter to a Unix timestamp. To update a subscription, set 'billing_cycle_anchor' to 'now' or 'unchanged'." }, { "name": "ERROR_SUBSCRIPTION_BILLING_CYCLE_ANCHOR_NOT_VALID", "description": "The request tried to create or update a subscription, but the date of the billing cycle anchor was set during the free trial period. The request was rejected. Corrective action: Set 'billing_cycle_anchor' with the same Unix timestamp as 'trial_end', or any time later than that." }, { "name": "ERROR_SUBSCRIPTION_BILLING_INCORRECT", "description": "The request attempted an operation that requires the 'billing' body parameter, but it was not set to a valid value. The request was rejected. Corrective action: Set 'billing' to 'pay_automatically'." }, { "name": "ERROR_SUBSCRIPTION_COUPON_CURRENCY", "description": "The request tried to add a coupon to a subscription, but the currency in the coupon did not match the currency of the plans in the subscription items. The request was rejected. Corrective action: Add a coupon that has the same currency as the plans in the subscription items." }, { "name": "ERROR_SUBSCRIPTION_NOT_FOUND", "description": "The request attempted an operation that requires a subscription ID, but the value was missing or was not recognized. The request was rejected. Corrective action: Provide a valid subscription ID." }, { "name": "ERROR_SUBSCRIPTION_TRIAL_END_AND_TRIAL_PERIOD_SET", "description": "The request tried to create or update a subscription, but both 'trial_end' and 'trial_period_days' were set. The request was rejected. Corrective action: Set 'trial_end' or 'trial_period_days', but not both." }, { "name": "ERROR_SUBSCRIPTION_TRIAL_END_NOT_VALID", "description": "The request tried to create or update a subscription, but the value of the 'trial_end' body parameter was not recognized. The request was rejected. Corrective action: Use a valid Unix timestamp for the 'trial_end' parameter. The maximum trial period length is 2 years. If there is no free trial, do not set this parameter." }, { "name": "ERROR_SUBSCRIPTION_TRIAL_PERIOD_ALREADY_DEFINED", "description": "The request tried to define a trial period for a subscription, but the trial period was already defined in the plan. The request was rejected. Corrective action: Set 'trial_from_plan' to false and define either 'trial_end' or 'trial_period_days'." }, { "name": "ERROR_SUBSCRIPTION_TRIAL_PERIOD_DAYS_NOT_VALID", "description": "The request tried to create or update a subscription, but the value of the 'trial_period_days' body parameter was not recognized. The request was rejected. Corrective action: Set 'trial_period_days' to an integer between 1 and 710. If there is no free trial, do not set this parameter." }, { "name": "ERROR_SUBSCRIPTION_TRIAL_PERIOD_NOT_VALID", "description": "The request tried to update the trial period of a subscription, but the end of the new trial period is before the current date. The request was rejected. Corrective action: Set 'trial_period_days' such that the last day of the trial period is after the current day." }, { "name": "ERROR_TAX_PERCENTAGE_NOT_VALID", "description": "The request attempted an operation that requires a tax percentage, but the value was not valid. The request was rejected. Corrective action: Set 'tax_percent' to zero or a positive decimal number." }, { "name": "ERROR_TRIAL_END_TRIAL_FROM_PLAN_TOGETHER", "description": "The request tried to create or update a subscription, but the 'trial_end' and 'trial_from_plan' body parameters were both set. The request was rejected. Corrective action: To set a trial period, set 'trial_end' or 'trial_from_plan', but not both." }, { "name": "ERROR_TRIAL_PERIOD_DAYS_MISMATCH", "description": "The request tried to add or update the list of subscription items in a subscription, but the plans in the subscription items did not all have the same value for 'trial_period_days'. The request was rejected. Corrective action: Update the plans so that they all have the same value for 'trial_period_days', or set 'trial_from_plan' in the subscription to 'false'." }, { "name": "ERROR_UPDATE_SUBSCRIPTION_STATUS_NOT_UPDATABLE", "description": "The request tried to update a free trial period for a subscription, but the subscription status was not 'active' or 'trialing'. The request was rejected. Corrective action: Create a new subscription with a new trial period." }, { "name": "INVALID_BILLING", "description": "The request tried to create a subscription or invoice, but the value of the 'billing' body parameter was not recognized. The request was rejected. Corrective action: Set 'billing' to 'pay_automatically'." }, { "name": "INVALID_STATUS", "description": "The request tried to retrieve a list of subscriptions, but the 'status' query parameter was not recognized. The request was rejected. Corrective action: Set 'status' to one of the following values: 'trialing', 'active', 'past_due', 'unpaid', 'canceled', 'all'" }, { "name": "INVALID_SUBSCRIPTION_ID", "description": "The request tried to process a subscription or subscription item, but the subscription was not found. The request was rejected. Corrective action: Use the ID of a valid subscription." }, { "name": "INVALID_SUBSCRIPTION_ITEMS", "description": "The request tried to create or update a subscription, but the subscription items could not be identified. The request was rejected. Corrective action: Set the 'subscription_items' body parameter to be an object or an array of not more than 20 objects." } ] }, { "product": "issuing", "id": "issued-card-object", "type": "type", "name": "IssuedCard", "description": "The Card Issuing object represents a card that you issue and brand for a customer. Your customer can use the card just like any other bank card. You can issue a virtual card for online use or a physical card. The customer's wallet funds the card. Each contact in a wallet can have one or more cards.", "fields": [ { "description": "ID of the Issued Card object, a string starting with **ci_**.", "type": [ { "type": "string", "startsWith": "ci_" } ], "name": "id", "required": true }, { "name": "activated_at", "type": [ { "type": "number" } ], "description": "Time that the card was activated, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "assigned_at", "type": [ { "type": "number" } ], "description": "Time that the card was assigned to a cardholder, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "bin", "type": [ { "type": "string" } ], "description": "Bank Identifier Number for the institution issuing the card. Response only.", "required": true }, { "name": "bin_number", "type": [ { "type": "string" } ], "description": "Bank Identifier Number. Webhook only.", "required": true }, { "name": "blocked_reason", "type": [ { "type": "string", "possibleValues": [ "blocked_reversible", "canceled", "compliance", "locked_incorrect_pin", "migrated", "none", "other", "reissued", "suspected_fraud" ] } ], "description": "Reason for blocking the card. One of the following:\n\\* **blocked_reversible**\n\\* **canceled**\n\\* **compliance**\n\\* **locked_incorrect_pin**\n\\* **migrated**\n\\* **none** - This is the default.\n\\* **other**\n\\* **reissued**\n\\* **suspected_fraud**", "required": true }, { "name": "card", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "Card number or ID of the Card object, which is a string starting with **card_**.", "required": true }, { "name": "card_color", "type": [ { "type": "number" } ], "description": "The color of the card, specified by one of the following:\n\\* HEX value - Color value\n\\* RGB - Color code, six HEX digits. See [here](https://www.w3.org/wiki/CSS/Properties/color/RGB).\n\\* RGBA - Color code\n\\* Name - CSS color name.\nIf `card_color` value is not specified, the color is black.", "required": true }, { "type": [ { "type": "string", "startsWith": "card_" } ], "name": "card_id", "description": "ID of the Card object. String starting with **card_**.", "required": true }, { "name": "card_number", "type": [ { "type": "string" } ], "description": "Actual card number.", "required": true }, { "name": "card_program", "description": "ID of the card program that the card is issued from. String starting with **cardprog_**. Required if `country` is blank or the client is licensed for two or more card programs in the country. To get the IDs your company is licensed for, contact [Client Support](doc:client-support).", "type": [ { "type": "string", "startsWith": "cardprog_" } ], "required": true }, { "description": "ID of the wallet contact that a card is assigned to. String starting with **cont_**.\n\nRelevant to [List Issued Cards](ref:list-issued-cards).", "type": [ { "type": "string", "startsWith": "cont_" } ], "name": "contact", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The country where the card is issued. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase. Required if `card_program` is blank.", "required": true }, { "name": "country_iso_alpha_2", "type": [ { "type": "string" } ], "description": "The country where the card is issued. Two-letter ISO 3166-1 ALPHA-2 code. Response only.", "required": true }, { "name": "created_at", "description": "Time of creation of the issued card object, in [*Unix time*](ref:glossary). Response only.", "type": [ { "type": "number" } ], "required": true }, { "name": "currency", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "Currency or list of currencies. Three-letter ISO 4217 code for each currency. Uppercase.", "required": true }, { "name": "currency_type", "type": [ { "type": "string", "possibleValues": [ "single", "multi" ] } ], "description": "Indicates how many currencies are supported. One of the following:\n\\* **single** - The card supports one currency.\n\\* **multi** - The card supports several currencies.\n\nResponse only.", "required": true }, { "name": "cvv", "type": [ { "type": "string" } ], "description": "Card security code.", "required": true }, { "name": "details", "type": [ { "type": "object" } ], "description": "Details of the issued card:\n\\* `bin` - Bank Identifier Number.\n\\* `last4` - Last four digits of the card.\n\\* `sub_bin` - Card program.\n\\* `expiration` - Month and year of the card expiration.\n\nWebhook only.", "required": true }, { "name": "expiration_month", "type": [ { "type": "string" } ], "description": "Expiration month of the card. Two digits. Relevant when the card issuer supports it for the country.", "required": true }, { "name": "expiration_year", "type": [ { "type": "string" } ], "description": "Expiration year of the card. Two digits. Relevant when the card issuer supports it for the country.", "required": true }, { "name": "ewallet_contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "description": "ID of the wallet contact that the card is assigned to. String starting with **cont_**.", "required": true }, { "name": "ewallet_contact", "type": [ { "type": "object", "id": "wallet-contact-object" } ], "description": "Describes details about the wallet contact that the card is assigned to. See [Wallet Contact Object](ref:wallet-contact-object). Response only.", "required": true }, { "name": "ewallet_contact_id", "type": [ { "type": "string", "startsWith": "cont_" } ], "description": "ID of the wallet contact that the card is assigned to. String starting with **cont_**.", "required": true }, { "name": "logo", "type": [ { "type": "string" } ], "description": "The URL of the logo image that appears on the card. If not specified, the name of the merchant appears.", "required": true }, { "name": "logo_orientation", "type": [ { "type": "string", "possibleValues": [ "landscape", "square", "portrait" ] } ], "description": "The orientation of the logo. One of the following:\n\\* **landscape** - This is the default.\n\\* **square**\n\\* **portrait**", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "description": "PIN code for the card. Must be a string.", "type": [ { "type": "string" } ], "name": "new_pin", "required": true }, { "name": "page_number", "type": [ { "type": "string" } ], "description": "Page number to retrieve. \n\nRelevant to [List Issued Cards](ref:list-issued-cards).", "required": true }, { "type": [ { "type": "string" } ], "description": "Number of results per page, up to 100. Default is **10**.\n\nRelevant to [List Issued Cards](ref:list-issued-cards).", "name": "page_size", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "block", "unblock" ] } ], "description": "Instruction to change the status of the card. One of the following:\n\\* **block** - Change status to **BLO**.\n\\* **unblock** - Change status from **BLO** to **ACT**.\n\nRelevant to request to update issued card.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "ACT", "BLO", "CAN", "IMP", "INA" ] } ], "description": "Status of the card. One of the following:\n\\* **ACT** - Active.\n\\* **BLO** - Blocked.\n\\* **CAN** - Cancelled.\n\\* **IMP** - Imported in bulk, but not yet personalized.\n\\* **INA** - Inactive.\n\nResponse only.", "required": true }, { "name": "sub_bin", "description": "Two-digit code for the card program. Response only.", "type": [ { "type": "string" } ], "required": true } ] }, { "product": "issuing", "parent": "issued-card-object", "id": "issue-card", "type": "request", "name": "IssueCardRequest", "description": "Use the POST method to issue a card to a wallet contact.\n\n> **Notes:** \n \\* Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.\n \\* The contact must have an address and a country.", "method": "POST", "path": "/v1/issuing/cards", "params": [], "body": [ { "name": "card_program", "type": [ { "type": "string", "startsWith": "cardprog_" } ], "required": false, "description": "ID of the card program that the card is issued from. String starting with **cardprog_**. Required if `country` is blank." }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase. Required if `card_program` is blank." }, { "name": "ewallet_contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "required": true, "description": "ID of the wallet contact that the card is assigned to. String starting with **cont_**." }, { "name": "expiration_month", "type": [ { "type": "string" } ], "required": false, "description": "Expiration month of the card." }, { "name": "expiration_year", "type": [ { "type": "string" } ], "required": false, "description": "Expiration year of the card." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "issued-card-object", "id": "activate-issued-card", "type": "request", "name": "ActivateIssuedCardRequest", "description": "Use the POST method to activate a card that was issued via the Rapyd issuing platform.\n\n> **Note:** Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.", "method": "POST", "path": "/v1/issuing/cards/activate", "params": [], "body": [ { "name": "card", "type": [ { "type": "string" } ], "required": true, "description": "Card number or card ID." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "issued-card-object", "id": "update-card-status", "type": "request", "name": "UpdateCardStatusRequest", "description": "Use the POST method to update a card that was issued via the Rapyd issuing platform. Use this method to block or unblock the card. \n> \\* To change the status from **ACT** (active) to **BLO** (blocked), set `status` to **block**.\n> \\* To change the status from **BLO** (blocked) to **ACT** (active), set `status` to **unblock**.\n\n> **Note:** Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.", "method": "POST", "path": "/v1/issuing/cards/status", "params": [], "body": [ { "name": "card", "type": [ { "type": "string" } ], "required": true, "description": "Card number or card ID." }, { "name": "status", "type": [ { "type": "string" } ], "required": true, "description": "Status of the card. One of the following: **block**, **unblock**" }, { "name": "blocked_reason", "type": [ { "type": "string" } ], "required": false, "description": "Reason for blocking the card. Relevant when the value of `status` is **block**." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "issued-card-object", "id": "set-pin-code", "type": "request", "name": "SetPINCodeRequest", "description": "Use the POST method to set the PIN code for an issued card. You can set any number other than 1111.\n\n> **Note:** Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.", "method": "POST", "path": "/v1/issuing/cards/pin", "params": [], "body": [ { "name": "card", "type": [ { "type": "string" } ], "required": true, "description": "Card number or card ID." }, { "name": "new_pin", "type": [ { "type": "string" } ], "required": true, "description": "PIN code. Must be a string." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "issued-card-object", "id": "personalize-issued-card", "type": "request", "name": "PersonalizeIssuedCardRequest", "description": "Use the POST method to assign an issued card to a contact in a Rapyd Wallet. This method is relevant to cards that are issued in bulk but not assigned to any specific person. It can be used only once per card.\n\n> **Note:** Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.", "method": "POST", "path": "/v1/issuing/cards/personalize", "params": [], "body": [ { "name": "card_number", "type": [ { "type": "string" } ], "required": true, "description": "Card number." }, { "name": "ewallet_contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "required": true, "description": "ID of the wallet contact that the card is issued to. String starting with **cont_**." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "issued-card-object", "id": "list-issued-cards", "type": "request", "name": "ListIssuedCardsRequest", "description": "Use the GET method to retrieve details of all issued cards. To filter the list for cards belonging to a specific wallet contact, use the 'contact' query parameter.\n\n> **Note:** Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.", "method": "GET", "path": "/v1/issuing/cards", "params": [], "body": [], "headers": [], "query": [ { "name": "contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "required": false, "description": "ID of a wallet contact. String starting with **cont_**." }, { "name": "page_number", "type": [ { "type": "string" } ], "required": false, "description": "Page number to retrieve." }, { "name": "page_size", "type": [ { "type": "string" } ], "required": false, "description": "Number of results per page." } ] }, { "product": "issuing", "parent": "issued-card-object", "id": "retrieve-issued-card-details", "type": "request", "name": "RetrieveIssuedCardDetailsRequest", "description": "Use the GET method to retrieve details of an issued card.\n\n> **Note:** Clients with [PCI](ref:glossary) certification can handle personal identifying information for cards.", "method": "GET", "path": "/v1/issuing/cards/{card}", "params": [ { "name": "card", "type": [ { "type": "string", "startsWith": "ci_" } ], "required": true, "description": "ID of the issued card. String starting with **ci_** or **card_**." } ], "body": [], "headers": [], "query": [] }, { "product": "issuing", "parent": "issued-card-object", "id": "simulate-blocking-a-card", "type": "request", "name": "SimulateBlockingACardRequest", "description": "When a third party sends Rapyd a stop notification for an issued card, Rapyd sets the card status to **BLO** (blocked) and sends you the **Card Issuing Blocked** webhook.\n\nUse the POST method in the sandbox to simulate the third-party stop notification. \n\nThis method triggers the **Card Issuing Blocked** webhook. See [Webhook - Card Issuing Blocked](ref:webhook-card-issuing-blocked).\n\nTo unblock the card, see [Update Card Status](ref:update-card-status).\n\n**Prerequisites:**\n \\* [Issue Card](ref:issue-card)\n \\* [Activate Issued Card](ref:activate-issued-card)", "method": "POST", "path": "/v1/issuing/cards/simulate_block", "params": [], "body": [ { "name": "card_id", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the card. String starting with **card_**." }, { "name": "blocked_reason", "type": [ { "type": "string" } ], "required": false, "description": "Reason for blocking the card." } ], "headers": [], "query": [] }, { "product": "disburse", "id": "plan-object-disburse", "type": "type", "name": "Plan", "description": "", "fields": [ { "description": "Unique ID for this payment plan. Legal input includes alphanumeric characters and the underscore (_) character. If the merchant does not define an ID, Rapyd generates a string starting with **plan\\_**.", "type": [ { "type": "string" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount to pay out, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time the `plan` object was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase.", "required": true }, { "name": "interval", "type": [ { "type": "string", "possibleValues": [ "day", "week", "month", "year", "day", "week", "month", "year" ] } ], "description": "Specifies the units used in defining the payout cycle. One of the following:\n* **day**\n* **week**\n* **month**\n* **year**\n\nMaximum interval is 1 year.\n\nWhen `interval_count` is set to **1**, the cycle ends at the following times:\n* **day**: Cycle ends after one day at 1:00 AM GMT time.\n* **week**: Cycle ends after seven days at 1:00 AM GMT time.\n* **month**: Cycle ends on the same day on the next month at 1:00 AM GMT time. For example, a monthly cycle that started on Jan. 23 will end on Feb. 23 at 1:00 AM GMT. In scenarios where the day does not exist in the next month, the cycle will end on the last day of the next month at 1:00 AM GMT. For example, a monthly cycle that started on Oct. 31 will end on Nov. 30 at 1:00 AM GMT.\n* **year**: Cycle ends on the same date on the next year at 1:00 AM GMT time. In a leap year, a cycle that started on Feb. 29 will end on the next year on Feb. 28 at 1:00 AM GMT.", "required": true }, { "name": "interval_count", "type": [ { "type": "number" } ], "description": "Number of time intervals in the payout cycle. Integer.\n\nThe payout cycle is defined in the `interval` and `interval_count` fields of the plan.\nFor example, to set the payout cycle to three months, set the following fields:\n \"interval\": \"month\",\n \"interval_count\": 3,", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "nickname", "type": [ { "type": "string" } ], "description": "Brief description of the plan.", "required": true }, { "name": "product", "type": [ { "type": "string" } ], "description": "The ID of the product that this plan is for.\n\nFor more information, see [Product Object](ref:product-object).", "required": true } ] }, { "product": "collect", "id": "return-object", "type": "type", "name": "Return", "description": "The Return object represents a return of an order of goods.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "orre_" } ], "description": "ID of the Return object. String starting with **orre_**.", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "\\* **In request:** In each item of type **sku**, the cost of one individual item, in units specified in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.\n\n\\* **In response:** Total amount of the order, the sum of the amount of the 'shipping' items, plus the `amount` of the tax, plus `amount` times `quantity` of each of the 'sku' items. Decimal. Read-only.", "required": true }, { "name": "created", "type": [ { "type": "number" } ], "description": "When the order was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the 'item' objects. Uppercase.", "required": true }, { "name": "items", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Each item describes one charge in the invoice. \n\nSee ***Items Object***, below.", "required": true }, { "name": "order", "description": "ID of the Order object. String starting with **order_**.", "type": [ { "type": "string", "startsWith": "order_" } ], "required": true }, { "name": "refund", "type": [ { "type": "string", "startsWith": "refund_" } ], "description": "ID of the Return object. String starting with **refund_**.", "required": true } ] }, { "product": "collect", "parent": "return-object", "id": "create-a-return-against-an-order", "type": "request", "name": "CreateAReturnAgainstAnOrderRequest", "description": "Use the POST method to make a return against an order. The maximum amount of the return is the amount of the order.\n\n> **Note:** It is the responsibility of the merchant to validate the `quantity` of the items in the return against the `quantity` of the items in the order.", "method": "POST", "path": "/v1/orders/{order}/returns", "params": [ { "name": "order", "type": [ { "type": "string", "startsWith": "order_" } ], "required": true, "description": "ID of the order to return. String starting with **order_**." } ], "body": [ { "name": "items", "type": [ { "type": "string" } ], "required": true, "description": "Array of objects. Required fields: `parent` (if `type` is **sku**), `amount`, `type`, `quantity`" } ], "headers": [], "query": [] }, { "product": "collect", "parent": "return-object", "id": "retrieve-a-return", "type": "request", "name": "RetrieveAReturnRequest", "description": "Use the GET method to retrieve the details of a return.", "method": "GET", "path": "/v1/order_returns/{order_return}", "params": [ { "name": "order_return", "type": [ { "type": "string", "startsWith": "orre_" } ], "required": true, "description": "ID of the return. String starting with **orre_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "return-object", "id": "list-returns", "type": "request", "name": "ListReturnsRequest", "description": "Use the GET method to retrieve a list of all order returns.", "method": "GET", "path": "/v1/order_returns", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the order created after the last order you want to retrieve a return from." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of returns to list. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the order created before the first order you want to retrieve a return from." } ] }, { "product": "collect", "parent": "return-object", "id": "return-errors", "type": "enum", "name": "ReturnError", "values": [ { "name": "ERROR_CREATE_ORDER_RETURN_ITEM", "description": "The request tried to create a return against an order, but one of the items in the return could not be created. The request was rejected. Corrective action: Check all input parameters." }, { "name": "ERROR_GET_ORDER_RETURN", "description": "The request tried to retrieve a return on an order, but the order was not found. The request was rejected. Corrective action: Use the ID of a valid return, a string starting with 'orre'." }, { "name": "ERROR_MISSING_ORDER_ID", "description": "The request attempted an operation that requires an order, but the order was not found. The request was rejected. Corrective action: Use the ID of a valid order, a string starting with 'order'." }, { "name": "ERROR_RETURN_ORDER_INVALID_ITEM_QUANTITY", "description": "The request tried to create a return against an order, but the quantity was missing or not a positive integer, or the item was already returned, or the item in the return does not match any item in the order. The request was rejected. Corrective action: Check all input fields." }, { "name": "ERROR_RETURN_ORDER_INVALID_ORDER", "description": "The request tried to create a return against an order, but the order was not found. The request was rejected. Corrective action: Use the ID of an order that is in 'paid', 'fulfilled' or 'returned' status." }, { "name": "ERROR_RETURN_ORDER_INVALID_SHIPPING_ITEM", "description": "The request tried to create a return against an order, but the SKU was not found. The request was rejected. Corrective action: Set 'parent' in each object in the 'items' array to the ID of an SKU in the order." }, { "name": "ERROR_RETURN_ORDER_INVALID_TAX_ITEM", "description": "The request tried to create a return against an order, but the item was a tax item and was not found in the order. The request was rejected. Corrective action: Check all input fields." }, { "name": "ERROR_RETURN_ORDER_RETURN_ITEM", "description": "The request tried to create a return against an order, but the order item was not found in the order. The request was rejected. Corrective action: Check all input fields." } ] }, { "product": "issuing", "id": "remote-authorization-object", "type": "type", "name": "RemoteAuthorization", "description": "Rapyd sends authorization requests to your remote authorization server when the card network requests approval of a transaction on a card issued to a Rapyd Wallet. Remote authorization is relevant to clients who have implemented the service.\n\nIf you are set up for remote authorization, you can enable or disable the service using the Client Portal.\n\nSee also [Remote Authorization](doc:remote-authorization).", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "cardauth_" } ], "description": "ID of the authorization. String starting with **cardauth_**.", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the transaction, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.", "required": true }, { "name": "auth_code", "type": [ { "type": "string" } ], "description": "Authorization code provided by client.", "required": true }, { "name": "auth_response", "type": [ { "type": "object", "fields": [ { "name": "code", "type": [ { "type": "unknown" } ] }, { "name": "message", "type": [ { "type": "unknown" } ] } ] } ], "description": "Response related to an authorization. Contains the following fields: \n* `code` - **00** indicates success. Other codes indicate rejection. \n* `message` - Descriptive text.\n\nResponse only.", "required": true }, { "type": [ { "type": "string", "startsWith": "cardauth_" } ], "name": "authorization_id", "description": "ID of the authorization. String starting with **cardauth_**. Response only.", "required": true }, { "name": "card_id", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "ID of the card. String starting with **card_**.", "required": true }, { "name": "card_transaction_id", "type": [ { "type": "string", "startsWith": "cit_" } ], "description": "ID of the transaction. String starting with **cit_**. Response only.", "required": true }, { "description": "Time of creation of the authorization, in [*Unix time*](ref:glossary). Response only.", "name": "created_at", "type": [ { "type": "number" } ], "required": true }, { "name": "currency", "description": "Currency of the transaction. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "Currency of the transaction. Three-letter ISO 4217 code. Uppercase. Response only.", "required": true }, { "name": "fx_rate", "type": [ { "type": "string" } ], "description": "The exchange rate. Response only.", "required": true }, { "name": "is_remote_auth", "type": [ { "type": "boolean" } ], "description": "Indicates whether remote authorization is enabled. Response only.", "required": true }, { "name": "merchant_category_code", "type": [ { "type": "string" } ], "description": "Four-digit merchant category code (MCC) of the initiator of the transaction, as defined in ISO 18245.", "required": true }, { "name": "merchant_identification_code", "type": [ { "type": "string" } ], "description": "Reserved. Response only.", "required": true }, { "type": [ { "type": "string" } ], "name": "merchant_name_location", "description": "Name and location of the merchant. Maximum 40 characters.", "required": true }, { "name": "remote_auth_endpoint", "type": [ { "type": "string" } ], "description": "The URL where the remote authorization is sent. Response only.", "required": true }, { "name": "remote_auth_response", "type": [ { "type": "object", "fields": [ { "name": "authorization_id", "type": [ { "type": "unknown" } ] }, { "name": "response_code", "type": [ { "type": "unknown" } ] }, { "name": "auth_code", "type": [ { "type": "unknown" } ] } ] } ], "description": "Response to a successful remote authorization request. Contains the following fields: \n* `authorization_id` - ID of the authorization. String starting with **cardauth_**. \n* `response_code` - Code returned by the client in the response to the remote authorization request. \n* `auth_code` - Authorization code returned by the client in the response to the remote authorization request. \n\nResponse only.", "required": true }, { "name": "retrieval_reference_number", "type": [ { "type": "string" } ], "description": "Retrieval reference number for a card transaction. Appears in the response to [List Issued Card Transactions](ref:list-issued-card-transactions).", "required": true }, { "name": "reversed_authorization_id", "description": "ID of the authorization reversal. String starting with **cardauth_**. Response only.", "type": [ { "type": "string", "startsWith": "cardauth_" } ], "required": true }, { "name": "status", "description": "Status of the authorization. One of the following:\n* **COMPLETED**\n* **ERROR**\n* **NEW**\n* **REVERSED**\n\nResponse only.", "type": [ { "type": "string", "possibleValues": [ "COMPLETED", "ERROR", "NEW", "REVERSED" ] } ], "required": true }, { "name": "transaction_amount", "description": "Amount debited from the Rapyd Wallet. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Response only.", "type": [ { "type": "number" } ], "required": true }, { "name": "transaction_currency_code", "description": "Original transaction currency, if different from the currency credited to the Rapyd Wallet. Three-letter ISO 4217 code. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "The type of request.", "required": true } ] }, { "product": "issuing", "parent": "remote-authorization-object", "id": "simulate-a-card-authorization-request", "type": "request", "name": "SimulateACardAuthorizationRequestRequest", "description": "If you have implemented Remote Authorization, Rapyd sends authorization requests to your remote authorization server when the card network requests approval of a transaction on a card issued to a Rapyd Wallet. \n\nUse this method in the sandbox to simulate Rapyd's request to your authorization server. The response contains all the fields you must send to Rapyd when you receive an authorization request in production.\n\nThis method triggers the **Card Issuing Sale** webhook. This webhook contains the same information as the response.\n\nSee also [Remote Authorization](doc:remote-authorization).\n\n**Prerequisites:**\n * [Issue Card](ref:issue-card)\n * [Activate Issued Card](ref:activate-issued-card)", "method": "POST", "path": "/v1/issuing/cards/authorization", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the authorization, in units of the currency defined in `currency`. Decimal." }, { "name": "card_id", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the card. String starting with **card_**." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Defines the currency for the amount. Three-letter ISO 4217 code. Uppercase." }, { "name": "merchant_category_code", "type": [ { "type": "string" } ], "required": false, "description": "Four-digit merchant category code (MCC) of the initiator of the transaction, as defined in [ISO 18245](https://www.iso.org/standard/33365.html)." }, { "name": "merchant_name_location", "type": [ { "type": "string" } ], "required": false, "description": "Name and location of the merchant. Maximum 40 characters. Default is 'TEST MERCHANT'." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "remote-authorization-object", "id": "simulate-a-card-authorization-reversal", "type": "request", "name": "SimulateACardAuthorizationReversalRequest", "description": "The retail location where a card was used for a purchase can send a reversal through the card network to cancel a previous authorization request. This can occur when the transaction is not completed within the time required by the card issuer. When Rapyd receives a request for reversal from the card network, it reverses the transaction and sends you a webhook. \n\nUse this method in the sandbox to simulate the retail location's reversal and trigger the webhook.\n\n**Prerequisites:**\n \\* [Issue Card](ref:issue-card)\n \\* [Activate Issued Card](ref:activate-issued-card)\n \\* [Simulate a Card Authorization Request](ref:simulate-a-card-authorization-request)", "method": "POST", "path": "/v1/issuing/cards/reversal", "params": [], "body": [ { "name": "auth_code", "type": [ { "type": "string" } ], "required": true, "description": "Authorization code provided by client. See results example in [Simulate a Card Authorization Request](ref:simulate-a-card-authorization-request)." }, { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the authorization, in units of the currency defined in `currency`. Decimal." }, { "name": "card_id", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the card. String starting with **card_**." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Defines the currency for the transaction. Three-letter ISO 4217 code. Uppercase." }, { "name": "retrieval_reference_number", "type": [ { "type": "string" } ], "required": true, "description": "Retrieval reference number for the card transaction." } ], "headers": [], "query": [] }, { "product": "collect", "id": "payment-method-type-object", "type": "type", "name": "PaymentMethodType", "description": "The Payment Method object describes a method of payment that can be used in the Rapyd platform.", "fields": [ { "name": "id", "type": [ { "type": "string" } ], "description": "ID of the Payment Method Type object.", "required": true }, { "description": "The billing address associated with the card.\n\nFor more information, see [Address Object](ref:address-object).", "type": [ { "type": "object", "id": "address-object" } ], "name": "address", "required": true }, { "name": "amount_range_per_currency", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Indicates the amount range for the payment method's currencies. Each object contains the following fields: \n* **currency** - Three-letter ISO 4217 format of currency.\n* **maximum_amount** - The maximum payment amount.\n* **minimum_amount** - The minimum payment amount.", "required": true }, { "name": "bin_details", "type": [ { "type": "object", "fields": [ { "name": "bin_number", "type": [ { "type": "unknown" } ] }, { "name": "country", "type": [ { "type": "unknown" } ] }, { "name": "funding", "type": [ { "type": "unknown" } ] }, { "name": "bank", "type": [ { "type": "unknown" } ] } ] } ], "description": "Bank Identification Number (BIN) details. Read-only. Object containing the following fields:\n* `bin_number` - BIN number\n* `country` - The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.\n* `funding` - Type of card funding. One of the following:\n * **credit**\n * **debit**\n * **prepaid**\n * **unknown**\n* `bank` - Name of the issuing bank.\n\nRelevant to cards.", "required": true }, { "name": "category", "description": "Category of payment method. Possible values:\n* **bank_redirect**\n* **bank_transfer**\n* **card**\n* **cash**\n* **ewallet**\n* **rapyd_ewallet**\n\nResponse only.", "type": [ { "type": "string", "possibleValues": [ "bank_redirect", "bank_transfer", "card", "cash", "ewallet", "rapyd_ewallet" ] } ], "required": true }, { "name": "country", "description": "Name of the country where this payment method is in use. Two-letter ISO 3166-1 alpha-2 code. Uppercase.\n\nTo determine the code for a country, see [List Countries](ref:list-countries).", "type": [ { "type": "string" } ], "required": true }, { "name": "currencies", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "A list of currencies in use in the country for this type of payment method. Three-letter ISO 4217 format. Uppercase. Response only.", "required": true }, { "name": "customer", "type": [ { "type": "string" } ], "description": "Name of the customer. Relevant to cards.\n\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "fields", "type": [ { "type": "object", "id": "retrieve-payment-method-required-fields" } ], "description": "Contains several fields that are used in creating the specific payment method. These fields always contain the same value for a payment method, so they are included in the payment method object.\n\nTo determine what fields are required for the payment method, see [Get Payment Method Required Fields](ref:retrieve-payment-method-required-fields).\n\nFor more fields, see the `payment_options` field in the response to [List Payment Methods](ref:list-payment-methods).\n\n**Note:** The 'fields' object can contain only fields that are either required or optional. A field with an unknown name will throw an error.", "required": true }, { "name": "fingerprint", "type": [ { "type": "string" } ], "description": "Hash of the card number, expiration date and CVV. Read-only.\n\nRelevant to cards.", "required": true }, { "name": "image", "description": "A URL to the image of the icon for the type of payment method. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "is_cancelable", "type": [ { "type": "boolean" } ], "description": "Indicates whether a payment made with this payment method can be canceled. Response only.", "required": true }, { "type": [ { "type": "boolean" } ], "name": "is_expirable", "description": "Indicates whether the merchant can set an expiration time for the customer to complete the payment. Response only.", "required": true }, { "type": [ { "type": "boolean" } ], "name": "is_online", "description": "Indicates whether the payment is completed immediately online. Response only.", "required": true }, { "name": "last4", "type": [ { "type": "string" } ], "description": "Last four digits of the card number. Read-only.\n\nRelevant to cards.", "required": true }, { "name": "maximum_expiration_seconds", "type": [ { "type": "number" } ], "description": "The maximum time (in seconds) that the merchant can set for completing the payment. Relevant when `is_expirable` is **true**. Response only.", "required": true }, { "name": "minimum_expiration_seconds", "type": [ { "type": "number" } ], "description": "The minimum time (in seconds) that the merchant can set for completing the payment. Relevant when `is_expirable` is **true**. Response only.", "required": true }, { "name": "name", "description": "The name of the payment method, in user-friendly terms. For example, 'Ireland Visa card'. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "payment_flow_type", "type": [ { "type": "string", "possibleValues": [ "bank redirect", "bank transfer", "card", "otc", "ewallet" ] } ], "description": "Indicates how the customer completes the payment transaction. Possible values:\n* **bank redirect** - The customer is directed to another URL to complete the bank payment.\n* **bank transfer** - Customer makes a transfer directly from the customer's bank to a bank account.\n* **card** - Rapyd charges the customer's card. \n* **otc** - The customer pays in cash at a Rapyd point-of-sale location. To find nearby locations, see [Methods - eWallet](#methods-ewallet).\n* **ewallet** - The customer pays from an eWallet.\n\nResponse only.", "required": true }, { "name": "payment_method_options", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Additional fields required for the payment method. These values might vary from one use to the next, so they are not saved as part of the payment method object. \n\nIn the request to create payment, these fields appear in the 'payment_method_options' object.\n\nTo determine the fields required, run [Get Payment Method Required Fields](ref:get-payment-method-required-fields).\n\nSee ***Options Objects***, below.", "required": true }, { "name": "payment_options", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Additional fields of the Payment object which are required for the payment.\n\nIn the request to create payment, these fields appear in the root of the body of the request.\n\nTo determine the fields required, run [Get Payment Method Required Fields](ref:get-payment-method-required-fields).\n\nSee ***Options Objects***, below.", "required": true }, { "name": "status", "type": [ { "type": "number" } ], "description": "Indicates the status of the payment method. One of the following values:\n* **1** - Valid.", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Name of the payment method type. For example, **it_visa_card**.\n\nTo get a list of payment methods for a country, use [List Payment Methods by Country](ref:retrieve-all-payment-methods-by-country).", "required": true } ] }, { "product": "collect", "parent": "payment-method-type-object", "id": "list-payment-methods-by-country", "type": "request", "name": "ListPaymentMethodsByCountryRequest", "description": "Use GET to retrieve a list of all payment methods available for a country. You can filter the results by specifying the `currency` query parameter.\n\nYou can also use the Client Portal. Navigate to **My Account > Settings > Payment Methods**.", "method": "GET", "path": "/v1/payment_methods/country", "params": [], "body": [], "headers": [], "query": [ { "name": "country", "type": [ { "type": "string" } ], "required": true, "description": "Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "The three-letter ISO 4217 code for the currency. Uppercase." } ] }, { "product": "collect", "parent": "payment-method-type-object", "id": "get-payment-method-required-fields", "type": "request", "name": "GetPaymentMethodRequiredFieldsRequest", "description": "Use GET to retrieve the required fields for a payment method. The fields are returned as a list of objects. The name of each field appears in the `name` field of the response.\n\n**NOTE:** Rapyd employs a unique variant of regex. Please note the following differences:\n \\* A single backslash matches a backslash as an ordinary character.\n \\* A backslash followed by an alphabetic character matches a string of two characters.\n \\* A special character such as \\n is indicated as \\\\n.", "method": "GET", "path": "/v1/payment_methods/required_fields/{type}", "params": [ { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "The `type` of the payment method." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-method-type-object", "id": "payment-method-errors", "type": "enum", "name": "PaymentMethodError", "values": [ { "name": "ERROR_GET_PAYMENT_METHOD_TYPE", "description": "The request attempted an operation that requires a payment method, but the payment method type was not recognized or is not available for this merchant. Corrective action: For the 'type' field in the 'payment_method' object or in the 'data' object, use a payment method type that this merchant is authorized to use." }, { "name": "ERROR_UPDATE_CARD_CVV_NOT_UPDATABLE", "description": "The request tried to update a card, but it tried to set a new value for the 'cvv' field. The 'cvv' field cannot be updated. The request was rejected. Corrective action: Do not change the 'cvv' field." }, { "name": "ERROR_UPDATE_PAYMENT_METHOD", "description": "The request tried to update a payment method, but one or more fields were missing or contained incorrect values. The request was rejected. Corrective action: Check all input fields. For details, see the API Reference." }, { "name": "INVALID_PAYMENT_METHOD", "description": "The request tried to perform an operation that requires a payment method, but the payment method was not found. The request was rejected. Corrective action: Use the correct payment method ID or payment method object." }, { "name": "INVALID_PAYMENT_METHOD_TYPE", "description": "The request tried to perform an operation that requires a payment method type, but the type was not recognized. The request was rejected. Corrective action: To find payment method types for a country, use 'List Payment Methods by Country'." }, { "name": "INVALID_REQUIRED_PAYMENT_METHOD_FIELDS", "description": "The request attempted an operation that requires a payment method, but the required fields were missing. The request was rejected. Corrective action: Run 'Get Payment Method Required Fields'. Inside the 'payment_method' object, populate the 'fields' object with all required fields." }, { "name": "MISSING_PAYMENT_METHOD_REQUIRED_FIELD", "description": "The request attempted an operation that requires fields for a payment method, but a field parameter was missing or did not have a valid value. The request was rejected. Corrective action: The end of the response_code shows the name of the field. Provide this field with a proper value." }, { "name": "PAYMENT_METHOD_FIELD_NOT_UPDATABLE", "description": "The request tried to update a payment method of a customer, but it tried to set a new value for a field that does not exist or is not modifiable. The request was rejected. Corrective action: Do not change the value of the field named at the end of the error code." }, { "name": "UNKNOWN_PAYMENT_METHOD_FIELD", "description": "The request attempted an operation that requires an object describing a payment method, but there was an extra field in the 'fields' object. The name of the extra field appears at the end of the response code. The request was rejected. Corrective action: Populate the 'fields' object with only the fields that are required." } ] }, { "product": "disburse", "id": "sender-object", "type": "type", "name": "Sender", "description": "The Sender object saves the details of a sender in payout transactions.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "sender_" } ], "description": "ID of the Sender object. String starting with **sender_**. Response only.", "required": true }, { "name": "company_name", "type": [ { "type": "string" } ], "description": "Name of the sender company. Relevant when `entity_type` is **company**.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "deleted", "type": [ { "type": "boolean" } ], "description": "Indicates whether a request to delete a sender from the Rapyd platform succeeded. Response only.", "required": true }, { "name": "entity_type", "type": [ { "type": "string", "possibleValues": [ "individual", "company" ] } ], "description": "Type of entity. One of the following values:\n* **individual**\n* **company**", "required": true }, { "name": "first_name", "type": [ { "type": "string" } ], "description": "First name of the sender. Relevant when `entity_type` is **individual**.", "required": true }, { "name": "identification_type", "type": [ { "type": "string", "possibleValues": [ "drivers_license", "identification_id", "international_passport", "residence_permit", "social_security", "work_permit" ] } ], "description": "Type of identification document for the sender. When `entity_type` is **company**, this field must be **company_registered_number**. \nWhen `entity_type` is **individual**, one of the following values:\n\\* **drivers_license**\n\\* **identification_id**\n\\* **international_passport**\n\\* **residence_permit**\n\\* **social_security**\n\\* **work_permit**", "required": true }, { "name": "identification_value", "type": [ { "type": "string" } ], "description": "Identification number on the document mentioned in `identification_type`.", "required": true }, { "name": "last_name", "type": [ { "type": "string" } ], "description": "Last name of the sender. Relevant when `entity_type` is **individual**.", "required": true }, { "name": "sender", "type": [ { "type": "string", "startsWith": "sender_" } ], "description": "ID of the Sender object. String starting with **sender_**.", "required": true } ] }, { "product": "disburse", "parent": "sender-object", "id": "create-sender", "type": "request", "name": "CreateSenderRequest", "description": "Use the POST method to create a payout sender. The response provides a unique sender ID, which you can use in place of the 'sender' object for [Create Payout](ref:create-payout).\n\n> **Note:** In addition to the required fields documented below, you must include all other sender fields listed in the response to [Get Payout Required Fields](ref:get-payout-required-fields), and you must conform to the regex provided. \n> To create a sender that you can use with multiple payout methods, include all fields that are required by each payout method. \n> The client is responsible for including all required fields.\n> \n> The additional fields used in the 'Create Sender - individual' example are for the 'ca_general_bank' payout method.\n> The additional field used in the 'Create Sender - company' example is for the 'us_ach_bank' payout method.", "method": "POST", "path": "/v1/payouts/sender", "params": [], "body": [ { "name": "company_name", "type": [ { "type": "string" } ], "required": false, "description": "Name of the sender company. Relevant when `entity_type` is **company**." }, { "name": "country", "type": [ { "type": "string" } ], "required": true, "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase." }, { "name": "entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the sender. One of the following: **individual**, **company**" }, { "name": "first_name", "type": [ { "type": "string" } ], "required": false, "description": "First name of the sender. Relevant when `entity_type` is **individual**." }, { "name": "identification_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of identification document for the sender." }, { "name": "identification_value", "type": [ { "type": "string" } ], "required": true, "description": "Identification number on the document mentioned in `identification_type`." }, { "name": "last_name", "type": [ { "type": "string" } ], "required": false, "description": "Last name of the sender. Relevant when `entity_type` is **individual**." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "sender-object", "id": "retrieve-sender", "type": "request", "name": "RetrieveSenderRequest", "description": "Use the GET method to retrieve details of a payout sender.\n\n> **Note:** The 'Retrieve Sender - individual' response includes additional fields for the 'ca_general_bank' payout method.\n> The 'Retrieve Sender - company' response includes an additional field for the 'us_ach_bank' payout method.", "method": "GET", "path": "/v1/payouts/sender/{sender}", "params": [ { "name": "sender", "type": [ { "type": "string", "startsWith": "sender_" } ], "required": true, "description": "ID of the 'sender' object. String starting with **sender_**." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "sender-object", "id": "delete-sender", "type": "request", "name": "DeleteSenderRequest", "description": "Use the DELETE method to delete a payout sender from the Rapyd platform.", "method": "DELETE", "path": "/v1/payouts/sender/{sender}", "params": [ { "name": "sender", "type": [ { "type": "string", "startsWith": "sender_" } ], "required": true, "description": "ID of the 'sender' object. String starting with **sender_**." } ], "body": [], "headers": [], "query": [] }, { "product": "issuing", "id": "issued-card-transaction-object", "type": "type", "name": "IssuedCardTransaction", "description": "The Issued Card Transaction Object holds information about transactions made with a card issued to a Rapyd Wallet.", "fields": [ { "description": "ID of the issued card transaction object. String starting with **cit_**.", "type": [ { "type": "string", "startsWith": "cit_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the transaction, in units defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Response only.", "required": true }, { "name": "auth_code", "type": [ { "type": "string" } ], "description": "Authorization code sent to the merchant. Relevant to authorizations approved by Rapyd. Response only.", "required": true }, { "name": "authorization_approved_by", "type": [ { "type": "string", "possibleValues": [ "Rapyd", "Client" ] } ], "description": "Approver of the transaction when remote authorization is used. See [Remote Authorization](doc:remote-authorization). One of the following:\n\\* **Rapyd**\n\\* **Client**\n\nResponse only.", "required": true }, { "name": "bin", "type": [ { "type": "string" } ], "description": "The first 6 digits of the card number. Response only.", "required": true }, { "name": "card", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "ID of the card. String starting with **card_**.", "required": true }, { "type": [ { "type": "string", "startsWith": "card_" } ], "name": "card_id", "description": "ID of the card. String starting with **card_**. Response only.", "required": true }, { "name": "card_program", "type": [ { "type": "string", "startsWith": "cardprog_" } ], "description": "ID of the card program that the card is issued from. String starting with **cardprog_**. Response only.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the transaction object, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "The currency of the transaction. Three-letter ISO 4217 code. Uppercase. Response only.", "required": true }, { "name": "end_date", "type": [ { "type": "number" } ], "description": "Timestamp of the last transaction or later, in [*Unix time*](ref:glossary).", "required": true }, { "name": "fx_rate", "description": "The exchange rate. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "issuing_txn_type", "type": [ { "type": "string", "possibleValues": [ "sale", "reversal", "adjustment", "refund" ] } ], "description": "Type of the transaction. One of the following:\n\\* **sale**\n\\* **reversal**\n\\* **adjustment**\n\\* **refund**\n\nResponse only.", "required": true }, { "name": "last4", "description": "The last 4 digits of the card number. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "max_amount", "type": [ { "type": "number" } ], "description": "Transactions smaller than a specific amount.", "required": true }, { "name": "merchant_category_code", "type": [ { "type": "string" } ], "description": "Four-digit merchant category code (MCC) of the initiator of the transaction, as defined in [ISO 18245](https://www.iso.org/standard/33365.html). Response only.", "required": true }, { "name": "merchant_name_location", "type": [ { "type": "string" } ], "description": "Name and location of the merchant. Maximum 40 characters. Response only.", "required": true }, { "name": "merchant_name_search", "description": "Filters the results to return only transactions that have this string as part of the name or location.", "type": [ { "type": "string" } ], "required": true }, { "name": "min_amount", "type": [ { "type": "number" } ], "description": "Transactions greater than a specific amount.", "required": true }, { "name": "original_transaction_id", "type": [ { "type": "string" } ], "description": "ID of the original card transaction. Response only.", "required": true }, { "name": "original_txn_amount", "type": [ { "type": "number" } ], "description": "Original amount for FX transactions, when `currency` is different from `original_txn_currency`. Response only.", "required": true }, { "name": "original_txn_currency", "description": "Original currency in FX transaction. Three-letter ISO 4217 code. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "page_number", "type": [ { "type": "string" } ], "description": "Page number to retrieve.", "required": true }, { "name": "page_size", "type": [ { "type": "number" } ], "description": "Number of results per page.", "required": true }, { "name": "pos_entry_mode", "description": "The mode of the POS entry. One of the following:\n\\* **magstripe**\n\\* **manual_entered**\n\\* **emv**\n\\* **emv_standin**\n\\* **nfc**\n\\* **network_token**\n\\* **ecommerce**\n\\* **3ds_ecommerce**\n\\* **adjustment**\n\nResponse only.", "type": [ { "type": "string", "possibleValues": [ "magstripe", "manual_entered", "emv", "emv_standin", "nfc", "network_token", "ecommerce", "3ds_ecommerce", "adjustment" ] } ], "required": true }, { "name": "retrieval_reference_number", "description": "Retrieval reference number for a card transaction. Appears in the response to [List Issued Card Transactions](ref:list-issued-card-transactions). Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "start_date", "type": [ { "type": "number" } ], "description": "Timestamp of the first transaction or later, in [*Unix time*](ref:glossary).", "required": true }, { "name": "systems_trace_audit_number", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "transaction", "type": [ { "type": "string", "startsWith": "cit_" } ], "description": "ID of the card transaction. String starting with **cit_**.", "required": true }, { "name": "wallet_transaction_id", "type": [ { "type": "string", "startsWith": "wt_" } ], "description": "ID of the wallet transaction. String starting with **wt_**. Response only.", "required": true } ] }, { "product": "issuing", "parent": "issued-card-transaction-object", "id": "list-issued-card-transactions", "type": "request", "name": "ListIssuedCardTransactionsRequest", "description": "Use the GET method to retrieve a list of transactions for a specific issued card.", "method": "GET", "path": "/v1/issuing/cards/{card}/transactions", "params": [ { "name": "card", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the issued card. String starting with **card_**." } ], "body": [], "headers": [], "query": [ { "name": "start_date", "type": [ { "type": "number" } ], "required": false, "description": "Timestamp of the first transaction or later, in [*Unix time*](ref:glossary)." }, { "name": "end_date", "type": [ { "type": "number" } ], "required": false, "description": "Timestamp of the last transaction or later, in [*Unix time*](ref:glossary)." }, { "name": "min_amount", "type": [ { "type": "number" } ], "required": false, "description": "Transactions greater than a specific amount." }, { "name": "max_amount", "type": [ { "type": "number" } ], "required": false, "description": "Transactions smaller than a specific amount." }, { "name": "merchant_name_search", "type": [ { "type": "string" } ], "required": false, "description": "Filters the results to return only transactions that have this string as part of the name or location." }, { "name": "page_size", "type": [ { "type": "number" } ], "required": false, "description": "Number of results per page." }, { "name": "page_number", "type": [ { "type": "string" } ], "required": false, "description": "Page number to retrieve." } ] }, { "product": "issuing", "parent": "issued-card-transaction-object", "id": "retrieve-issued-card-transaction-details", "type": "request", "name": "RetrieveIssuedCardTransactionDetailsRequest", "description": "Use the GET method to retrieve details of a specific transaction from a specific issued card.", "method": "GET", "path": "/v1/issuing/cards/{card}/transactions/{transaction}", "params": [ { "name": "card", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the issued card. String starting with **card_**." }, { "name": "transaction", "type": [ { "type": "string", "startsWith": "cit_" } ], "required": true, "description": "ID of the card transaction. String starting with **cit_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "id": "subscription-item-object-collect", "type": "type", "name": "SubscriptionItem", "description": "A subscription item is a product of type **service** that is charged to the customer periodically. It is associated with a specific subscription that defines how the billing is done.", "fields": [ { "description": "ID of the Subscription Item object. String starting with **subi\\_**.", "type": [ { "type": "string" } ], "name": "id", "required": true }, { "name": "created", "type": [ { "type": "number" } ], "description": "The time the subscription item was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "plan", "type": [ { "type": "object", "id": "plan-object" } ], "description": "The pricing plan that defines the product and pricing structure associated with this subscription item.\n\nSee [Plan Object](ref:plan-object).", "required": true }, { "name": "prorate", "type": [ { "type": "boolean" } ], "description": "Determines whether the charge is prorated, in the following situations:\n* When a subscription item is switched from one subscription to another in a billing cycle.\n* When a new customer starts in the middle of a billing cycle.\n* When the customer cancels the subscription.", "required": true }, { "name": "proration_date", "type": [ { "type": "number" } ], "description": "Indicates the date in [*Unix time*](ref:glossary) in the middle of the billing period that is the start or end of the prorated item. The other end is determined by the `period_start` or `period_end` of the invoice.\n\nIf the subscription and its subscription item have different proration dates, the proration takes place on the earlier of the two dates.", "required": true }, { "name": "quantity", "type": [ { "type": "number" } ], "description": "The number of units of the service defined in the plan. Integer. This number can be updated during the billing cycle using [Update Subscription](ref:update-subscription) or [Update Subscription Item](ref:update-subscription-item).", "required": true }, { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "description": "ID of the subscription that this item belongs to. String starting with **sub_**.\n\nSee [Subscription Object](ref:subscription-object).", "required": true } ] }, { "product": "collect", "parent": "subscription-item-object-collect", "id": "create-subscription-item", "type": "request", "name": "CreateSubscriptionItemRequest", "description": "Use the POST method to create a subscription item and add it to an existing subscription.\n\nThis method triggers the **Customer Subscription Item Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/subscription_items", "params": [], "body": [ { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "plan", "type": [ { "type": "string" } ], "required": true, "description": "ID of the plan assigned to this subscription item." }, { "name": "prorate", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether the charge is prorated when a subscription item is switched from one subscription to another in a billing cycle." }, { "name": "proration_date", "type": [ { "type": "number" } ], "required": false, "description": "Indicates the date in the middle of the billing period that is the start of the prorated charges." }, { "name": "quantity", "type": [ { "type": "number" } ], "required": false, "description": "The number of units of the service defined in the plan." }, { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription that this item belongs to. String starting with **sub_**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-item-object-collect", "id": "update-subscription-item", "type": "request", "name": "UpdateSubscriptionItemRequest", "description": "Use the POST method to change or modify a subscription item.\n\nThis method triggers the **Customer Subscription Item Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/subscription_items/{subscription_item}", "params": [ { "name": "subscription_item", "type": [ { "type": "string", "startsWith": "subi_" } ], "required": true, "description": "ID of the subscription item. String starting with **subi_**." } ], "body": [ { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "prorate", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether the charge is prorated when a subscription item is switched from one subscription to another in a billing cycle." }, { "name": "proration_date", "type": [ { "type": "number" } ], "required": false, "description": "Indicates the date in the middle of the billing period that is the start or end of the prorated charges. Relevant to the first and last billing cycles." }, { "name": "quantity", "type": [ { "type": "number" } ], "required": false, "description": "The number of units of the product or service." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-item-object-collect", "id": "retrieve-subscription-item", "type": "request", "name": "RetrieveSubscriptionItemRequest", "description": "Use the GET method to retrieve the details of a subscription item.", "method": "GET", "path": "/v1/subscription_items/{subscription_item}", "params": [ { "name": "subscription_item", "type": [ { "type": "string", "startsWith": "subi_" } ], "required": true, "description": "ID of the subscription item. String starting with **subi_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-item-object-collect", "id": "list-subscription-items", "type": "request", "name": "ListSubscriptionItemsRequest", "description": "Use the GET method to retrieve a list of all subscription items for a subscription.", "method": "GET", "path": "/v1/subscription_items", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the subscription item created after the last subscription item you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of subscription items to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the subscription item created before the first subscription item you want to retrieve." }, { "name": "subscription", "type": [ { "type": "string" } ], "required": true, "description": "ID of the subscription." } ] }, { "product": "collect", "parent": "subscription-item-object-collect", "id": "delete-subscription-item", "type": "request", "name": "DeleteSubscriptionItemRequest", "description": "Use the DELETE method to delete a subscription item from the Rapyd platform.\n\nThis method triggers the **Customer Subscription Item Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/subscription_items/{subscription_item}", "params": [ { "name": "subscription_item", "type": [ { "type": "string", "startsWith": "subi_" } ], "required": true, "description": "ID of the subscription item. String starting with **subi_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "subscription-item-object-collect", "id": "subscription-item-errors", "type": "enum", "name": "SubscriptionItemError", "values": [ { "name": "ERROR_CREATE_SUBSCRIPTION_ITEM", "description": "The request attempted an operation that requires a plan ID, but the value was missing or was not recognized. The request was rejected. Corrective action: Provide a valid plan ID." }, { "name": "ERROR_CURRENCY_OR_INTERVAL_MISMATCH", "description": "The request tried to add or update the list of subscription items in a subscription, but the plans in the subscription items did not all have the same values for 'currency' and 'interval'. The request was rejected. Corrective action: Include only plans that all have the same values for 'currency' and 'interval'." }, { "name": "ERROR_DELETE_LAST_SUBSCRIPTION_ITEM", "description": "The request tried to delete a subscription item from a subscription, but the subscription item is the only one in the subscription. The request was rejected. Corrective action: Delete the subscription." }, { "name": "ERROR_GET_SUBSCRIPTION_ITEM", "description": "The request tried to retrieve a subscription item, but the subscription item was not found. The request was rejected. Corrective action: Use a valid subscription item ID." }, { "name": "ERROR_PRORATION_DATE_NOT_VALID", "description": "The request attempted to set a proration date on a subscription item, but the date selected was not valid. The request was rejected. Corrective action: For ‘proration_date’, use a date within the current billing period." }, { "name": "ERROR_UPDATE_SUBSCRIPTION_ITEM_USAGE_TYPE", "description": "The request tried to update a subscription item, but the usage type in the new plan did not match the usage type in the old plan. The request was rejected. Corrective action: Choose a plan that has the same 'usage_type'. " }, { "name": "INVALID_PRORATE_VALUE", "description": "The request tried to set a proration date on a subscription item, but the value of 'prorate' was not valid. The request was rejected. Corrective action: Set 'prorate' to true." }, { "name": "INVALID_SUBSCRIPTION_ITEM_PRORATE", "description": "The request tried to create or update a subscription item, but the setting for the 'prorate' body parameter was not a Boolean. The request was rejected. Corrective action: Select a Boolean value for the 'prorate' parameter." }, { "name": "INVALID_SUBSCRIPTION_ITEM_PRORATION_DATE", "description": "The request attempted to set a proration date on a subscription item, but the date selected was not valid. The request was rejected. Corrective action: For 'proration_date', use a Unix timestamp within the current billing period." }, { "name": "INVALID_SUBSCRIPTION_ITEM_QUANTITY", "description": "The request tried to create a usage record for a subscription item, but the quantity was not valid or 'usage_type' in the relevant plan was set to 'metered'. The request was rejected. Corrective action: Use a positive integer for 'quantity' or create a new subscription item with a plan that has 'usage_type' set to 'metered'." }, { "name": "INVALID_SUBSCRIPTION_ITEM_USAGE_RECORD_TIMESTAMP", "description": "The request tried to create a usage record, but the value for the 'timestamp' body parameter was not in the correct format. The request was rejected. Corrective action: Use a valid Unix timestamp." } ] }, { "product": "disburse", "id": "beneficiary-tokenization-page-object", "type": "type", "name": "BeneficiaryTokenizationPage", "description": "The Beneficiary Tokenization Page object holds the details of the page that collects personal information directly from the customer. The page is created by an API call and completed by the customer in a user-friendly GUI page. When the process is complete, Rapyd sends [Webhook - Beneficiary Created](ref:webhook-beneficiary-created).", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "description": "\\* In [Create Beneficiary Tokenization Page](ref:create-beneficiary-tokenization-page): ID of the beneficiary tokenization page. String starting with **hp\\_ben\\_**.\n\n\\* In [Retrieve Beneficiary ID](ref:retrieve-beneficiary-id): ID of the beneficiary. String starting with **beneficiary_**.", "required": true }, { "name": "beneficiary_country", "description": "The two-letter ISO 3166-1 ALPHA-2 code for the beneficiary’s country. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "beneficiary_currency", "description": "Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "beneficiary_entity_type", "description": "Type of entity for the beneficiary. One of the following: \n\\* **individual**\n\\* **company**", "type": [ { "type": "string", "possibleValues": [ "individual", "company" ] } ], "required": true }, { "name": "beneficiary_id", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "description": "ID of the beneficiary. String starting with **beneficiary_**.", "required": true }, { "name": "beneficiary_optional_fields", "type": [ { "type": "object" } ], "description": "Additional information about the beneficiary. See **beneficiary_optional_fields Object**, below.", "required": true }, { "name": "beneficiary_validated", "type": [ { "type": "boolean" } ], "description": "Indicates whether the beneficiary has been validated. See [Validate Beneficiary](ref:validate-beneficiary).", "required": true }, { "name": "cancel_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected when the customer closes the beneficiary tokenization page before completing the operation. This URL overrides the fallback URL that was set in the Client Portal.", "required": true }, { "name": "category", "description": "The category of payout method. One of the following: \n\\* **bank**\n\\* **card** - US only.", "type": [ { "type": "string", "possibleValues": [ "bank", "card" ] } ], "required": true }, { "name": "complete_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected when tokenization is successful. This URL overrides the fallback URL that was set in the Client Portal.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the beneficiary’s country. Uppercase.", "required": true }, { "name": "currency", "description": "Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. Uppercase. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "entity_type", "description": "Type of entity for the beneficiary. One of the following: \n\\* **individual**\n\\* **company**", "type": [ { "type": "string", "possibleValues": [ "individual", "company" ] } ], "required": true }, { "name": "expiration", "description": "The page expiration date in [*Unix time*](ref:glossary). Response only.", "type": [ { "type": "number" } ], "required": true }, { "description": "Determines the default language of the hosted page. \nThe values are documented in [Hosted Page Language Support](ref:hosted-page-language-support).", "type": [ { "type": "string" } ], "name": "language", "required": true }, { "name": "merchant_customer_support", "type": [ { "type": "object", "fields": [ { "name": "email", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] }, { "name": "phone_number", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contact details for customer support, containing the following fields:\n\\* `email` - Email address.\n\\* `url` - URL for the client's customer support service.\n\\* `phone_number` - Phone number for contacting the client's customer support service.\n\nTo configure these fields, use the Client Portal.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "Identifier for the beneficiary. Defined by the client.", "required": true }, { "description": "The page expiration date in [*Unix time*](ref:glossary). The default is 14 days from the creation of the page.", "type": [ { "type": "number" } ], "name": "page_expiration", "required": true }, { "name": "payout_currency", "description": "Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "description": "The payout method type selected by the customer.", "required": true }, { "name": "payout_method_types_exclude", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "List of payout methods that are excluded from display on the beneficiary tokenization page.", "required": true }, { "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "name": "payout_method_types_include", "description": "Array of strings. List of payout methods that are displayed on the beneficiary tokenization page.", "required": true }, { "name": "redirect_url", "description": "URL where the customer is redirected for entering details.", "type": [ { "type": "string" } ], "required": true }, { "name": "sender_country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the sender’s country. Uppercase.", "required": true }, { "name": "sender_currency", "description": "Currency paid from the sender’s wallet. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "sender_entity_type", "description": "Type of entity for the sender. One of the following: \n\\* **individual**\n\\* **company**.", "type": [ { "type": "string", "possibleValues": [ "individual", "company" ] } ], "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "NEW", "SUCCESS", "ERROR" ] } ], "description": "Indicates whether the page was created successfully. One of the following values:\n\\* **NEW** - New beneficiary.\n\\* **SUCCESS** - Created.\n\\* **ERROR** - Failed.", "required": true }, { "name": "timestamp", "type": [ { "type": "string" } ], "description": "Timestamp for the request to create the beneficiary tokenization object page, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "tokenization_page", "type": [ { "type": "string" } ], "description": "ID of the beneficiary tokenization page. String starting with **hp\\_ben\\_**.", "required": true } ] }, { "product": "disburse", "parent": "beneficiary-tokenization-page-object", "id": "create-beneficiary-tokenization-page", "type": "request", "name": "CreateBeneficiaryTokenizationPageRequest", "description": "Use the POST method to create a beneficiary tokenization page. This method creates a URL for a page where the customer enters details required for payouts to the beneficiary's bank account. \n> **Notes:** \n> \\* If `beneficiary_country` is not specified, the customer specifies the country on the beneficiary tokenization page.\n> \\* For an individual beneficiary, if `first_name` and `last_name` are not specified, the customer provides this information on the beneficiary tokenization page.\n> \\* When the customer provides all required information, a beneficiary object is created and Rapyd sends a webhook to the client with the ID of the beneficiary object.", "method": "POST", "path": "/v1/hosted/disburse/beneficiary", "params": [], "body": [ { "name": "beneficiary_country", "type": [ { "type": "string" } ], "required": false, "description": "The two-letter ISO 3166-1 ALPHA-2 code for the beneficiary’s country." }, { "name": "beneficiary_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the beneficiary. One of the following: **individual**, **company**." }, { "name": "beneficiary_optional_fields", "type": [ { "type": "object", "id": "beneficiary-tokenization-page-object" } ], "required": false, "description": "Additional information about the beneficiary. See [Beneficiary Tokenization Page Object](ref:beneficiary-tokenization-page-object)." }, { "name": "cancel_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected when the hosted page is closed before the operation is complete." }, { "name": "category", "type": [ { "type": "string" } ], "required": false, "description": "The category of payout method." }, { "name": "complete_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected when tokenization is successful." }, { "name": "language", "type": [ { "type": "string" } ], "required": false, "description": "Determines the default language of the hosted page." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "Identifier for the beneficiary. Defined by the client." }, { "name": "page_expiration", "type": [ { "type": "number" } ], "required": false, "description": "Date and time of the page expiration, in [*Unix time*](ref:glossary)." }, { "name": "payout_currency", "type": [ { "type": "string" } ], "required": false, "description": "Currency accepted by the beneficiary’s bank account. Three-letter ISO 4217 code. Uppercase." }, { "name": "payout_method_types_exclude", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "required": false, "description": "Array of strings. List of payout methods that are excluded from display on the beneficiary tokenization page." }, { "name": "payout_method_types_include", "type": [ { "type": "string" } ], "required": false, "description": "Array of strings. List of payout methods that are displayed on the beneficiary tokenization page." }, { "name": "sender_country", "type": [ { "type": "string" } ], "required": true, "description": "The two-letter ISO 3166-1 ALPHA-2 code for the sender’s country." }, { "name": "sender_currency", "type": [ { "type": "string" } ], "required": false, "description": "Currency paid from the sender’s wallet. Three-letter ISO 4217 code. Uppercase." }, { "name": "sender_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the sender. One of the following: **individual**, **company**." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "beneficiary-tokenization-page-object", "id": "retrieve-beneficiary-id", "type": "request", "name": "RetrieveBeneficiaryIDRequest", "description": "Use the GET method to get the beneficiary ID after the customer provides all data required on the beneficiary tokenization page.", "method": "GET", "path": "/v1/hosted/disburse/beneficiary/{beneficiary_page}", "params": [ { "name": "beneficiary_page", "type": [ { "type": "string" } ], "required": true, "description": "ID of the beneficiary tokenization page. String starting with **hp\\_ben\\_**." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "beneficiary-tokenization-page-object", "id": "beneficiary-tokenization-errors", "type": "enum", "name": "BeneficiaryTokenizationError", "values": [ { "name": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_CATEGORY", "description": "The request tried to create a beneficiary tokenization page, but the payout category was not valid. The request was rejected. Corrective action: Set 'category' to 'bank' or 'card'." }, { "name": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_COMPANY_NAME", "description": "The request attempted to create a beneficiary with a hosted page, but the type of entity for the beneficiary was 'individual' and a company name was provided. The request was rejected. Corrective action: Set ‘sender_entity_type’ to ‘company’ or leave 'company_name' blank." }, { "name": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_EXPIRATION_TIMESTAMP", "description": "The request tried to create a beneficiary tokenization page, but the page expiration timestamp was not valid. The request was rejected. Corrective action: Set 'page_expiration' to a Unix timestamp in the future." }, { "name": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_IDENTIFICATION_TYPE", "description": "The request attempted to create a beneficiary with a hosted page, but the ID type was not valid. The request was rejected. Corrective action: In the 'beneficiary_optional_fields' object, set a valid value for 'identification_type'. For details, see the API reference." }, { "name": "ERROR_HOSTED_PAGE_BENEFICIARY_INVALID_IDENTIFICATION_VALUE", "description": "The request attempted to create a beneficiary with a hosted page, but the ID value was not valid. The request was rejected. Corrective action: In the 'beneficiary_optional_fields' object, set 'identification_value' to a string." }, { "name": "ERROR_HOSTED_PAGE_INVALID_BENEFICIARY_ENTITY_TYPE", "description": "The request attempted to create a beneficiary with a hosted page, but the type of entity for the beneficiary was not recognized. The request was rejected. Corrective action: Set 'beneficiary_entity_type' to 'individual' or 'company'." } ] }, { "product": "wallet", "id": "identity-verification-object", "type": "type", "name": "IdentityVerification", "description": "Methods for verifying the identity of an individual associated with a wallet.", "fields": [ { "name": "id", "description": "ID of the identity verification operation. String starting with **kycid_**.", "type": [ { "type": "string", "startsWith": "kycid_" } ], "required": true }, { "name": "additional_data", "type": [ { "type": "string" } ], "description": "Additional data. Response only.", "required": true }, { "name": "allow_multiple_checks", "type": [ { "type": "boolean" } ], "description": "Indicates whether multiple identity checks are allowed for a personal contact.\n\\* **true** - Enables multiple identity checks.\n\\* **false** - An identity check is allowed only the first time, or after a previous check resulted in error. This is the default.", "required": true }, { "name": "back_side_image", "description": "Base-64-encoded image of the back of the ID document. Maximum size: 8,000 pixels height or width, 5 MB.", "type": [ { "type": "string" } ], "required": true }, { "name": "back_side_image_mime_type", "description": "MIME type of the front side image of the identification document. One of the following:\n\\* **image/jpeg** - JPEG image. This is the default.\n\\* **image/png** - PNG image.", "type": [ { "type": "string" } ], "required": true }, { "name": "contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "description": "ID of the wallet contact. String starting with **cont_**.", "required": true }, { "name": "country", "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of the identity verification operation, in [*Unix time*](ref:glossary). Relevant to webhooks.", "required": true }, { "name": "date_of_birth", "type": [ { "type": "string" } ], "description": "Date of birth of the individual.", "required": true }, { "name": "document_sub_type", "type": [ { "type": "string" } ], "description": "Subtype of the identification document.", "required": true }, { "name": "document_type", "description": "Type of identification document. Two-letter code.\n\nFor types that are valid in the country, use [List Official Identification Documents](ref:list-official-identification-documents).", "type": [ { "type": "string" } ], "required": true }, { "name": "ewallet", "description": "ID of the Rapyd Wallet. String starting with **ewallet_**.", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true }, { "name": "ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the Rapyd Wallet. String starting with **ewallet_**. Relevant to webhooks.", "required": true }, { "name": "face_image", "description": "Base-64-encoded image of the face. Maximum size: 8,000 pixels height or width, 5 MB.", "type": [ { "type": "string" } ], "required": true }, { "name": "face_image_mime_type", "type": [ { "type": "string" } ], "description": "MIME type of the face image. One of the following:\n\\* **image/jpeg** - JPEG image. This is the default.\n\\* **image/png** - PNG image.", "required": true }, { "name": "face_validation", "type": [ { "type": "boolean" } ], "description": "Indicates whether face verification was performed.", "required": true }, { "name": "first_name", "type": [ { "type": "string" } ], "description": "First name of the individual.", "required": true }, { "name": "front_side_image", "description": "Base-64-encoded image of the front of the identification document. Maximum size: 8,000 pixels height or width, 5 MB.", "type": [ { "type": "string" } ], "required": true }, { "name": "front_side_image_mime_type", "type": [ { "type": "string" } ], "description": "MIME type of the front side image of the identification document. One of the following:\n* **image/jpeg** - JPEG image. This is the default.\n* **image/png** - PNG image.", "required": true }, { "name": "gender", "type": [ { "type": "string", "possibleValues": [ "male", "female" ] } ], "description": "Gender of the individual. One of the following values:\n* **male**\n* **female**\n**null**", "required": true }, { "name": "id_number", "type": [ { "type": "string" } ], "description": "ID number as shown on the identification document.", "required": true }, { "name": "images", "type": [ { "type": "string" } ], "description": "Link to the images that were used for this verification.", "required": true }, { "name": "is_address_extractable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the person's address can be extracted from the document. Read-only. Relevant to response to [List Official Identification Documents](ref:list-official-identification-documents).", "required": true }, { "name": "is_back_required", "type": [ { "type": "boolean" } ], "description": "Indicates whether the back of the document is required to establish identity. Read-only. Relevant to response to [List Official Identification Documents](ref:list-official-identification-documents).", "required": true }, { "name": "last_name", "type": [ { "type": "string" } ], "description": "Last name of the individual.", "required": true }, { "name": "name", "type": [ { "type": "string", "possibleValues": [ "ID card", "Passport" ] } ], "description": "Name of the identification document. One of the following:\n\\* **Driver's license**\n\\* **ID card**\n\\* **Passport**\nRead-only. Relevant to response to [List Official Identification Documents](ref:list-official-identification-documents).", "required": true }, { "name": "page_expiration", "description": "End of the time for completing the identity verification process, in [*Unix time*](ref:glossary). Minimum time: 1 day. Default is two weeks from creation of the page.", "type": [ { "type": "number" } ], "required": true }, { "name": "reference_id", "description": "ID of the identity verification request. Must be unique for each request. Defined by the client. Maximum length: 36 characters.", "type": [ { "type": "string" } ], "required": true }, { "name": "reject_reason", "type": [ { "type": "string" } ], "description": "Reason for not approving the individual.", "required": true }, { "name": "request_source", "type": [ { "type": "string" } ], "description": "Type of device that supplied the images.", "required": true }, { "name": "request_type", "description": "Determines the action that is taken on the request. One of the following: \n\\* **store** - Store the images on the Rapyd platform. \n\\* **verify** - Verify the identity of the person in the images.", "type": [ { "type": "string", "possibleValues": [ "store", "verify" ] } ], "required": true }, { "name": "send_callback", "type": [ { "type": "boolean" } ], "description": "Determines whether a webhook is sent with the results of the verification request. Default is **true**.", "required": true }, { "name": "state", "type": [ { "type": "string" } ], "description": "State of residence of the individual, as shown on the identification document.", "required": true }, { "description": "Status of the verified identity. One of the following:\n\\* **ACT** - The identity verification process is in progress.\n\\* **CLO** - The identity verification process is closed.\n\\* **NEW** -The identity verification process has not yet started.\n\nResponse only.", "name": "status", "type": [ { "type": "string", "possibleValues": [ "ACT", "CLO", "NEW" ] } ], "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Type of identification document. Two-letter code.\n\nFor types that are valid in the country, use [List Official Identification Documents](ref:list-official-identification-documents).", "required": true }, { "name": "valid_countries", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "verification_status", "type": [ { "type": "string", "possibleValues": [ "APPROVED", "NO_DOCUMENT_UPLOADED", "NOT_READABLE_DOCUMENT", "REJECTED", "UNSUPPORTED_COUNTRY", "UNSUPPORTED_TYPE" ] } ], "description": "Indicates whether the individual was approved. One of the following:\n\\* **APPROVED**\n\\* **NO_DOCUMENT_UPLOADED**\n\\* **NOT_READABLE_DOCUMENT**\n\\* **REJECTED**\n\\* **UNSUPPORTED_COUNTRY**\n\\* **UNSUPPORTED_TYPE**", "required": true } ] }, { "product": "wallet", "parent": "identity-verification-object", "id": "create-identity-verification-page", "type": "request", "name": "CreateIdentityVerificationPageRequest", "description": "Use the POST method to create a hosted page for verifying the identity of a personal contact for a Rapyd Wallet. The customer completes the process by accessing the URL returned in the response.", "method": "POST", "path": "/v1/hosted/idv", "params": [], "body": [ { "name": "contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "required": true, "description": "ID of the wallet contact. String starting with **cont_**." }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**." }, { "name": "page_expiration", "type": [ { "type": "number" } ], "required": false, "description": "End of the time for completing the identity verification process, in [*Unix time*](ref:glossary). Default is 14 days." }, { "name": "reference_id", "type": [ { "type": "string" } ], "required": true, "description": "ID of the identity verification request. Must be unique for each request." }, { "name": "request_type", "type": [ { "type": "string" } ], "required": false, "description": "Determines the action that is taken on the request. Default is **verify**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "identity-verification-object", "id": "list-official-identification-documents", "type": "request", "name": "ListOfficialIdentificationDocumentsRequest", "description": "Use the GET method to retrieve a list of the types of official identification documents for a country. Use this method to determine the types of documents to use for identification purposes, and also whether you need the reverse side of the document. You can filter your search results by country with the `country` query parameter.", "method": "GET", "path": "/v1/identities/types", "params": [], "body": [], "headers": [], "query": [ { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." } ] }, { "product": "wallet", "parent": "identity-verification-object", "id": "verify-identity", "type": "request", "name": "VerifyIdentityRequest", "description": "Use the POST method to verify the identity of an individual. The response to this request returns only the Rapyd ID and merchant reference ID that correspond to the identity verification request. The actual results of the identity check are contained in the webhook that is sent later. See [Webhook - Identity Verification](ref:webhook-identity-verification).\n\nThis method triggers the **Identity Verification** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/identities", "params": [], "body": [ { "name": "back_side_image", "type": [ { "type": "string" } ], "required": false, "description": "Base-64-encoded image of the back of the identity document." }, { "name": "back_side_image_mime_type", "type": [ { "type": "string" } ], "required": false, "description": "MIME type of the back side image of the identity document. Default is **image/jpeg**." }, { "name": "contact", "type": [ { "type": "string" } ], "required": false, "description": "ID of a personal contact for a company wallet." }, { "name": "country", "type": [ { "type": "string" } ], "required": true, "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "document_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of the identification document. Two-letter code. For valid types, use [List Official Identification Documents](ref:list-official-identification-documents)." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**." }, { "name": "face_image", "type": [ { "type": "string" } ], "required": true, "description": "Base-64-encoded image of the face." }, { "name": "face_image_mime_type", "type": [ { "type": "string" } ], "required": false, "description": "MIME type of the face image. Default is **image/jpeg**." }, { "name": "front_side_image", "type": [ { "type": "string" } ], "required": true, "description": "Base-64-encoded image of the front of the identity document." }, { "name": "front_side_image_mime_type", "type": [ { "type": "string" } ], "required": false, "description": "MIME type of the front side image of the identity document. Default is **image/jpeg**." }, { "name": "reference_id", "type": [ { "type": "string" } ], "required": true, "description": "ID of the identity verification request. Defined by the client. Must be unique for each request." }, { "name": "request_type", "type": [ { "type": "string" } ], "required": false, "description": "Determines the action that is taken on the request." }, { "name": "send_callback", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether a webhook is sent with the results of the verification request." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "identity-verification-object", "id": "identity-verification-errors", "type": "enum", "name": "IdentityVerificationError", "values": [ { "name": "ERROR_HOSTED_PAGE_INVALID_CONTACT", "description": "The request attempted a hosted page operation for identity verification process, but the contact was of type 'business' and the verification process is only for personal contacts. The request was rejected. Corrective action: Add a personal contact to the wallet and run the verification process on the personal contact." }, { "name": "ERROR_ID_VERIFICATION", "description": "The request tried to validate identity, but the operation failed. The request was rejected. Corrective action: Check all parameters and provide a unique reference ID for each identity verification operation, whether successful or unsuccessful." }, { "name": "ERROR_ID_VERIFICATION_ALREADY_COMPLETE", "description": "The request tried to verify the identity of a wallet contact, but the identity was already verified and cannot be verified twice. The request was rejected. Corrective action: None. Determine why multiple attempts were made to verify the same identity." }, { "name": "ERROR_ID_VERIFICATION_ALREADY_IN_PROGRESS", "description": "The request tried to verify the identity of a wallet contact, but the verification process is still pending. The request was rejected. Corrective action: Wait for the process to complete." }, { "name": "ERROR_ID_VERIFICATION_BACK_SIDE_IMAGE_ENCODING_INVALID", "description": "The request tried to validate identity, but the back side image provided was not properly encoded into Base64. The request was rejected. Corrective action: Convert the image into Base64 encoding, using all options that are required, as verified by your testing." }, { "name": "ERROR_ID_VERIFICATION_BACK_SIDE_IMAGE_MIME_TYPE_INVALID", "description": "The request tried to validate identity, but the back side image provided was not the correct MIME type. The request was rejected. Corrective action: Use a JPEG or PNG image." }, { "name": "ERROR_ID_VERIFICATION_BACK_SIDE_IMAGE_MISSING", "description": "The request tried to validate identity, but the required back side image was not found. The request was rejected. Corrective action: Submit the back side image with JPEG or PNG format, Base-64 encoded." }, { "name": "ERROR_ID_VERIFICATION_DUPLICATE_REFERENCE_ID", "description": "The request tried to validate identity, but the 'reference_id' body parameter was previously used. The request was rejected. Corrective action: Provide a unique reference ID for each identity verification operation, whether successful or unsuccessful." }, { "name": "ERROR_ID_VERIFICATION_IMAGE_NOT_VALID", "description": "The request tried to validate identity, but an image was not valid. The request was rejected. Corrective action: Use clear, readable images." }, { "name": "ERROR_ID_VERIFICATION_INVALID_BACK_SIDE_IMAGE_ENCODING", "description": "The request tried to validate identity, but the back side image provided was not properly encoded into Base64. The request was rejected. Corrective action: Convert the image into Base64 encoding, using all options that are required, as verified by your testing." }, { "name": "ERROR_ID_VERIFICATION_INVALID_DOCUMENT_TYPE", "description": "The request tried to validate identity, but the document provided was not a supported type. The request was rejected. Corrective action: Use 'List Official Identification Documents' to find the documents supported in the country." }, { "name": "ERROR_ID_VERIFICATION_INVALID_EWALLET", "description": "The request tried to validate identity, but the associated wallet was not found. Corrective action: In the 'ewallet' field, provide the wallet ID, a string starting with 'ewallet'." }, { "name": "ERROR_ID_VERIFICATION_INVALID_FACE_IMAGE_ENCODING", "description": "The request tried to validate identity, but the face image provided was not properly encoded into Base64. The request was rejected. Corrective action: Convert the image into Base64 encoding, using all options that are required, as verified by your testing." }, { "name": "ERROR_ID_VERIFICATION_INVALID_FACE_IMAGE_MIME_TYPE", "description": "The request tried to validate identity, but the face image provided was not the correct MIME type. The request was rejected. Corrective action: Use a JPEG or PNG image." }, { "name": "ERROR_ID_VERIFICATION_INVALID_FRONTSIDE_IMAGE_MIME_TYPE", "description": "The request tried to parse a document, but the front side image provided was not the correct MIME type. The request was rejected. Corrective action: Use a JPEG or PNG image." }, { "name": "ERROR_ID_VERIFICATION_INVALID_REFERENCE_ID", "description": "The request tried to verify identity, but the reference ID contains more than 36 characters. The request was rejected. Corrective action: Use a reference ID with 36 characters or less." }, { "name": "ERROR_ID_VERIFICATION_MISSING_BACK_SIDE_IMAGE", "description": "The request tried to parse a document, but the required back side image was not found. The request was rejected. Corrective action: Submit the back side image with JPEG or PNG format, Base-64 encoded." }, { "name": "ERROR_ID_VERIFICATION_MISSING_COUNTRY", "description": "The request tried to validate identity, but the 'country' body parameter was empty or missing. Corrective action: Provide the 2-letter ISO code for the country in uppercase letters." }, { "name": "ERROR_ID_VERIFICATION_MISSING_DOCUMENT_TYPE", "description": "The request tried to validate identity, but the 'document_type' body parameter was empty or missing. Corrective action: Use 'List Official Identification Documents' to find the document types that are supported in the country." }, { "name": "ERROR_ID_VERIFICATION_MISSING_EWALLET", "description": "The request tried to validate identity, but the 'ewallet' body parameter was empty or missing. Corrective action: Provide the wallet ID, a string starting with 'ewallet_'." }, { "name": "ERROR_ID_VERIFICATION_MISSING_EWALLET_ID", "description": "The request tried to validate identity, but the 'ewallet' body parameter was empty or missing. Corrective action: Provide the wallet ID, a string starting with 'ewallet_'." }, { "name": "ERROR_ID_VERIFICATION_MISSING_FACE_IMAGE", "description": "The request tried to validate identity, but the face image was missing. The request was rejected. Corrective action: Provide the face image." }, { "name": "ERROR_ID_VERIFICATION_MISSING_FRONTSIDE_IMAGE", "description": "The request tried to parse a document, but the required front side image was not found. The request was rejected. Corrective action: Submit the front side image with JPEG or PNG format, Base-64 encoded." }, { "name": "ERROR_ID_VERIFICATION_MISSING_REFERENCE_ID", "description": "The request tried to validate identity, but the 'reference_id' body parameter was empty or missing. Corrective action: Provide the merchant's reference ID for the identity verification operation." }, { "name": "ERROR_MAX_NUMBER_OF_IDENTITY_VERIFICATIONS", "description": "The request tried to validate identity, but the maximum number of requests for this individual has been reached. The request was rejected. Corrective action: None. Contact Client Support." }, { "name": "INVALID_DATE_OF_BIRTH", "description": "The request tried to add or update a date of birth, but it was not in the correct format or was a date in the future. The request was rejected. Corrective action: Provide a valid birthdate in mm/dd/yyyy format." }, { "name": "INVALID_IDENTIFICATION_NUMBER", "description": "The request tried to validate identity, but the ID number was missing or not recognized. The request was rejected. Corrective action: Provide the ID number and verify that it contains only alphanumeric characters and spaces." }, { "name": "INVALID_IDENTIFICATION_TYPE", "description": "The request tried to validate identity, but the document type was missing or not recognized. The request was rejected. Corrective action: Provide the required document type. To determine valid types, use 'List Official Identification Documents'." }, { "name": "INVALID_IMAGE_URL", "description": "The request attempted an operation that processed a URL for an image, but the operation failed. Corrective action: Provide a valid HTTP or HTTP URL with a JPG or PNG file extension." } ] }, { "product": "collect", "id": "sku-object", "type": "type", "name": "SKU", "description": "The SKU object describes a single item of physical inventory. The SKU is attached to a product where `type` is **goods**.\n\nAn SKU is a prerequisite for an order. See [Order Object](ref:order-object).", "fields": [ { "description": "ID of the SKU object. Alphanumeric characters and underscores (_). Defined by the merchant, or a string starting with **sku_**.", "type": [ { "type": "string", "startsWith": "sku_" } ], "name": "id", "required": true }, { "name": "active", "type": [ { "type": "boolean" } ], "description": "Indicates whether the product is currently being sold. Default is **false**.", "required": true }, { "name": "attributes", "type": [ { "type": "object" } ], "description": "Up to 5 alphanumeric key-value pairs defined by the merchant. For example:\n\n{\n\n> \"size\": 12,\n> \"color\": \"red\"\n\n}\n\nEach key must match a string in the 'attributes' list of the corresponding 'product' object.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of this SKU, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the `price` field. Uppercase.", "required": true }, { "name": "image", "type": [ { "type": "string" } ], "description": "URL of image associated with the product.", "required": true }, { "name": "inventory", "type": [ { "type": "object", "fields": [ { "name": "type", "type": [ { "type": "unknown" } ] }, { "name": "quantity", "type": [ { "type": "unknown" } ] }, { "name": "value", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contains the following fields:\n* `type` - One of the following values:\n * **finite** - Physical objects that can be counted.\n * **infinite** - Products such as downloadable software.\n * **bucket** - Products that are sold by measurable quantity.\n* `quantity` - The number of units available in inventory. Integer. Relevant when `type` is **finite**.\n* `value` - The status of the product on hand in inventory. Relevant when `type` is **bucket**. One of the following:\n * **in_stock** - A normal amount of product is available in inventory.\n * **limited** - There is enough product in inventory for small orders only.\n * **out_of_stock** - No product remains in inventory.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "package_dimensions", "type": [ { "type": "object", "fields": [ { "name": "height", "type": [ { "type": "unknown" } ] }, { "name": "length", "type": [ { "type": "unknown" } ] }, { "name": "weight", "type": [ { "type": "unknown" } ] }, { "name": "width", "type": [ { "type": "unknown" } ] } ] } ], "description": "Physical attributes of the SKU item. Contains the following fields:\n* `height`\n* `length`\n* `weight`\n* `width`\n\nThese fields are represented as numbers, but it is the responsibility of the merchant to define and interpret the relevant units of length and weight.", "required": true }, { "name": "price", "type": [ { "type": "number" } ], "description": "Price of one unit. Decimal.", "required": true }, { "name": "product", "type": [ { "type": "string" } ], "description": "ID of the product that this SKU relates to.\n\nFor more information, see [Product Object](ref:product-object).", "required": true }, { "name": "size", "type": [ { "type": "string" } ], "description": "The size of the SKU.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Time that this product was last updated, in [*Unix time*](ref:glossary). Response only.", "required": true } ] }, { "product": "collect", "parent": "sku-object", "id": "create-sku", "type": "request", "name": "CreateSKURequest", "description": "Use the POST method to create a SKU and attach it to a product. Relevant to products where `type` is **goods**. You can attach several SKUs to a single product.\n\nThis method triggers the **SKU Created** webhook. This webhook is not documented because it contains the same information as the response.\n\n**Note:** If the product defined an array of `attributes`, then you must include an `attributes` object that assigns values to those attributes, as in the example below.", "method": "POST", "path": "/v1/skus", "params": [], "body": [ { "name": "active", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the product is currently available for purchase." }, { "name": "attributes", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "required": false, "description": "Array of alphanumeric key-value pairs defined by the merchant. Each key must match a string in the 'attributes' list of the corresponding 'product' object." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in the `price` parameter. Uppercase." }, { "name": "id", "type": [ { "type": "string" } ], "required": false, "description": "ID of the 'sku' object. Alphanumeric characters and underscores (_)." }, { "name": "image", "type": [ { "type": "string" } ], "required": false, "description": "URL of image associated with the product." }, { "name": "inventory", "type": [ { "type": "object" } ], "required": true, "description": "'inventory' object {quantity, type, value}" }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "package_dimensions", "type": [ { "type": "string" } ], "required": false, "description": "Physical attributes of the SKU item. Object containing the following fields: `height`, `length`, `weight`, `width`" }, { "name": "price", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the price. Decimal." }, { "name": "product", "type": [ { "type": "string" } ], "required": true, "description": "ID of the product that this SKU relates to. The `type` field of the product must be set to **goods**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "sku-object", "id": "update-sku", "type": "request", "name": "UpdateSKURequest", "description": "Use the POST method to change or modify an SKU.\n\nThis method triggers the **SKU Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/skus/{sku}", "params": [ { "name": "sku", "type": [ { "type": "string" } ], "required": true, "description": "ID of the 'sku' object. String starting with the **sku_**." } ], "body": [ { "name": "active", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the product is currently available for purchase." }, { "name": "attributes", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "required": false, "description": "Array of alphanumeric key-value pairs defined by the merchant. Each key must match a string in the 'attributes' list of the corresponding 'product' object." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency used in the `price` parameter. Uppercase." }, { "name": "image", "type": [ { "type": "string" } ], "required": false, "description": "URL of image associated with the product." }, { "name": "inventory", "type": [ { "type": "object" } ], "required": false, "description": "Inventory object {quantity, type, value}. If this object appears in the request, `quantity` and `type` are required." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "package_dimensions", "type": [ { "type": "object" } ], "required": false, "description": "Physical attributes of the SKU item. Contains the following fields: `height`, `length`, `weight`, `width`" }, { "name": "price", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the price. Decimal." }, { "name": "product", "type": [ { "type": "string" } ], "required": false, "description": "ID of the product that this SKU relates to. The `type` field of the product must be set to **goods**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "sku-object", "id": "retrieve-sku", "type": "request", "name": "RetrieveSKURequest", "description": "Use the GET method to retrieve the details of an SKU.", "method": "GET", "path": "/v1/skus/{sku}", "params": [ { "name": "sku", "type": [ { "type": "string", "startsWith": "sku_" } ], "required": true, "description": "ID of the 'sku' object. String starting with **sku_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "sku-object", "id": "list-skus", "type": "request", "name": "ListSKUsRequest", "description": "Use the GET method to retrieve a list of all SKUs.", "method": "GET", "path": "/v1/skus", "params": [], "body": [], "headers": [], "query": [ { "name": "active", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether the query returns active SKUs or inactive SKUs. Default is **true**." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the SKU created before the first SKU you want to retrieve." }, { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the SKU created after the last SKU you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of SKUs to return. Range: 1-100. Default is 10." } ] }, { "product": "collect", "parent": "sku-object", "id": "delete-sku", "type": "request", "name": "DeleteSKURequest", "description": "Use the DELETE method to delete an SKU from the Rapyd platform.\n\nThis method triggers the **SKU Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/skus/{sku}", "params": [ { "name": "sku", "type": [ { "type": "string", "startsWith": "sku_" } ], "required": true, "description": "ID of the 'sku' object. String starting with **sku_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "sku-object", "id": "sku-errors", "type": "enum", "name": "SKUError", "values": [ { "name": "ERROR_CREATE_SKU_WRONG_PRODUCT_TYPE", "description": "The request tried to create an SKU, but the 'type' field of the associated product was set to 'service'. The request was rejected. Corrective action: Set 'product' to the ID of a product that has its 'type' field set to 'goods'." }, { "name": "ERROR_DELETE_SKU", "description": "The request tried to delete an SKU, but the SKU was not found. The request was rejected. Corrective action: Determine whether the SKU was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_SKU", "description": "The request tried to retrieve an SKU, but the SKU was not found. The request was rejected. Corrective action: Use a valid SKU ID." }, { "name": "ERROR_INVALID_SKU_ID", "description": "The request attempted an operation that requires an SKU, but the SKU was not found. The request was rejected. Corrective action: Use a valid SKU ID." }, { "name": "INVALID_INVENTORY_QUANTITY", "description": "The request tried to create or update an SKU, but the quantity specified for the inventory was not a number. The request was rejected. Corrective action: Specify a positive number." }, { "name": "INVALID_SKU_ATTRIBUTES", "description": "The request tried to create or update an SKU, but the attributes did not match the list of attributes defined in the associated product. The request was rejected. Corrective action: Define attributes that match the list of attributes defined in the associated product." }, { "name": "INVALID_SKU_INVENTORY_TYPE", "description": "The request tried to create or update an SKU, but the 'type' field in the 'inventory' object was not recognized. The request was rejected. Corrective action: Use 'finite', 'infinite' or 'bucket'." }, { "name": "INVALID_SKU_PRICE", "description": "The request tried to create or update an SKU, but the 'price' was not recognized. The request was rejected. Corrective action: Use a valid decimal for the price." }, { "name": "INVALID_SKU_PRODUCT_TOKEN", "description": "The request tried to create or update an SKU, but the product was not recognized. The request was rejected. Corrective action: For 'product', use the ID of a valid product of type 'goods'." } ] }, { "product": "disburse", "id": "beneficiary-object", "type": "type", "name": "Beneficiary", "description": "The Beneficiary object saves the details of a beneficiary in payout transactions.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "description": "ID of the 'beneficiary' object. String starting with **beneficiary_**. Response only.", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Maximum payout amount to validate, in units of the currency defined in `sender_currency`. Decimal.", "required": true }, { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "description": "ID of the 'beneficiary' object. String starting with **beneficiary_**.", "required": true }, { "name": "category", "type": [ { "type": "string", "possibleValues": [ "bank", "card", "cash", "ewallet", "rapyd_ewallet" ] } ], "description": "The category of payout method type. One of the following:\n\\* **bank**\n\\* **card**\n\\* **cash**\n\\* ** ewallet** - non-Rapyd eWallet\n\\* **rapyd_ewallet** - Rapyd wallet\n\nMust match the category of the payout method.", "required": true }, { "name": "company_name", "type": [ { "type": "string" } ], "description": "Name of the beneficiary company. Relevant when `entity_type` is **company**.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "default_payout_method_type", "type": [ { "type": "string" } ], "description": "The default type of payout method for the beneficiary. Use [List Payout Method Types](ref:list-payout-method-types) for a list of supported types for a country.", "required": true }, { "type": [ { "type": "boolean" } ], "name": "deleted", "description": "Indicates whether a request to delete a beneficiary from the Rapyd platform succeeded. Response only.", "required": true }, { "name": "entity_type", "type": [ { "type": "string", "possibleValues": [ "individual", "company" ] } ], "description": "Type of entity. One of the following values:\n\\* **individual**\n\\* **company**", "required": true }, { "name": "first_name", "type": [ { "type": "string" } ], "description": "First name of the beneficiary. Relevant when `entity_type` is **individual**.", "required": true }, { "name": "identification_type", "type": [ { "type": "string", "possibleValues": [ "drivers_license", "identification_id", "international_passport", "residence_permit", "social_security", "work_permit" ] } ], "description": "Type of identification document for the beneficiary. When `entity_type` is **company**, this field must be **company_registered_number**. \nWhen `entity_type` is **individual**, one of the following values:\n\\* **drivers_license**\n\\* **identification_id**\n\\* **international_passport**\n\\* **residence_permit**\n\\* **social_security**\n\\* **work_permit**", "required": true }, { "name": "identification_value", "type": [ { "type": "string" } ], "description": "Identification number on the document mentioned in `identification_type`.", "required": true }, { "name": "last_name", "type": [ { "type": "string" } ], "description": "Last name of the beneficiary. Relevant when `entity_type` is **individual**.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "ID defined by the merchant. Rapyd does not validate this value to enforce uniqueness.", "required": true }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "description": "The `type` of the payout method. Set to a value in the response to [List Payout Method Types](ref:list-payout-method-types).", "required": true }, { "name": "sender_country", "type": [ { "type": "string" } ], "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "sender_currency", "type": [ { "type": "string" } ], "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "sender_entity_type", "type": [ { "type": "string" } ], "description": "Type of entity for the sender. One of the following: **individual**, **company**", "required": true }, { "name": "validated", "type": [ { "type": "boolean" } ], "description": "Indicates whether the format of payout beneficiary details is valid for the payout method type. Response only.", "required": true } ] }, { "product": "disburse", "parent": "beneficiary-object", "id": "create-beneficiary", "type": "request", "name": "CreateBeneficiaryRequest", "description": "Use the POST method to create a payout beneficiary. The response provides a unique beneficiary ID, which you can use in place of the Beneficiary object for [Create Payout](ref:create-payout).\n\nThis method triggers the **Beneficiary Created** webhook. This webhook contains the same information as the response.\n\n> **Note:** In addition to the required fields documented below, you must include all other beneficiary fields listed in the response to [Get Payout Required Fields](ref:get-payout-required-fields), and you must conform to the regex provided. \n> To create a beneficiary that you can use with multiple payout methods, include all fields that are required by each payout method. \n> The client is responsible for including all required fields.\n> \n> The additional fields used in the 'Create Beneficiary - individual' example are for the 'ca_general_bank' payout method.\n> The additional fields used in the 'Create Beneficiary - company' example are for the 'us_ach_bank' payout method.", "method": "POST", "path": "/v1/payouts/beneficiary", "params": [], "body": [ { "name": "category", "type": [ { "type": "string" } ], "required": true, "description": "The category of payout method type. One of the following: **bank**, **card**, **cash**, **ewallet**, **rapyd_ewallet**" }, { "name": "company_name", "type": [ { "type": "string" } ], "required": false, "description": "Name of the beneficiary company. Relevant when `entity_type` is **company**." }, { "name": "country", "type": [ { "type": "string" } ], "required": true, "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase." }, { "name": "default_payout_method_type", "type": [ { "type": "string" } ], "required": false, "description": "The default type of payout method for the beneficiary." }, { "name": "entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the beneficiary. One of the following: **individual**, **company**" }, { "name": "first_name", "type": [ { "type": "string" } ], "required": false, "description": "First name of the beneficiary. Relevant when `entity_type` is **individual**." }, { "name": "identification_type", "type": [ { "type": "string" } ], "required": false, "description": "Type of identification document for the beneficiary." }, { "name": "identification_value", "type": [ { "type": "string" } ], "required": false, "description": "Identification number on the document mentioned in `identification_type`." }, { "name": "last_name", "type": [ { "type": "string" } ], "required": false, "description": "Family name of the beneficiary. Relevant when `entity_type` is **individual**." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "ID defined by the client." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "beneficiary-object", "id": "validate-beneficiary", "type": "request", "name": "ValidateBeneficiaryRequest", "description": "Use the POST method to validate the format of the payout beneficiary details for a payout method type. \n\nYou can validate a beneficiary multiple times for different payout methods.\n\nYou can enter a Beneficiary object or a previously created beneficiary ID. \n\n> **Note:** In addition to the required fields for [Create Beneficiary](ref:create-beneficiary), the Beneficiary object must include all required fields for the beneficiary listed in the response to [Get Payout Required Fields](ref:get-payout-required-fields).\n> \n> The examples include additional fields for the 'us_ach_bank' payout method.", "method": "POST", "path": "/v1/payouts/beneficiary/validate", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "Maximum payout amount to validate, in units of the currency defined in `sender_currency`. Decimal." }, { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "required": true, "description": "String starting with **beneficiary_** or the object describing the beneficiary." }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "required": true, "description": "The `type` of the payout method. Set to value included in response to [List Payout Method Types](ref:list-payout-method-types)." }, { "name": "sender_country", "type": [ { "type": "string" } ], "required": true, "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "sender_currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase." }, { "name": "sender_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the sender. One of the following: **individual**, **company**" } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "beneficiary-object", "id": "retrieve-beneficiary", "type": "request", "name": "RetrieveBeneficiaryRequest", "description": "Use the GET method to retrieve details of a payout beneficiary.\n\n> **Note:** The 'Retrieve Beneficiary - individual' response includes additional fields for the 'ca_general_bank' payout method.\n> The 'Retrieve Beneficiary - company' response includes additional fields for the 'us_ach_bank' payout method.", "method": "GET", "path": "/v1/payouts/beneficiary/{beneficiary}", "params": [ { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "required": true, "description": "ID of the 'beneficiary' object. String starting with **beneficiary_**." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "beneficiary-object", "id": "delete-beneficiary", "type": "request", "name": "DeleteBeneficiaryRequest", "description": "Use the DELETE method to delete a payout beneficiary from the Rapyd platform.", "method": "DELETE", "path": "/v1/payouts/beneficiary/{beneficiary}", "params": [ { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "required": true, "description": "ID of the 'beneficiary' object. String starting with **beneficiary_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "id": "address-object", "type": "type", "name": "Address", "description": "The Address object describes the address of a customer. It can be added to a Customer object, a Payment Method object, a wallet contact, or the `business_details` field of a business wallet.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "address_" } ], "description": "ID of the Address object. String starting with **address_**.", "required": true }, { "name": "canton", "type": [ { "type": "string" } ], "description": "Name of the canton administrative subdivision, as used in banking.", "required": true }, { "name": "city", "type": [ { "type": "string" } ], "description": "City portion of the address. Required for issuance of a card to the wallet contact.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.\n\nTo determine the code for a country, see [List Countries](ref:retrieve-all-countries).", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the 'address' object, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "district", "type": [ { "type": "string" } ], "description": "Name of the district administrative subdivision, as used in banking.", "required": true }, { "name": "line_1", "type": [ { "type": "string" } ], "description": "Line 1 of the address, such as a building number and street name.", "required": true }, { "name": "line_2", "type": [ { "type": "string" } ], "description": "Line 2 of the address, such as a suite or apartment number, or the name of a named building.", "required": true }, { "name": "line_3", "type": [ { "type": "string" } ], "description": "Line 3 of the address.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "name", "type": [ { "type": "string" } ], "description": "The name of a contact person or an \"in care of\" person at this address.", "required": true }, { "name": "phone_number", "type": [ { "type": "string" } ], "description": "Phone number associated with this specific address in E.164 format. Must be unique.", "required": true }, { "name": "state", "type": [ { "type": "string" } ], "description": "State or province portion of the address.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Time of the last update to the Address object, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "zip", "type": [ { "type": "string" } ], "description": "Postal code portion of the address.", "required": true } ] }, { "product": "collect", "parent": "address-object", "id": "create-address", "type": "request", "name": "CreateAddressRequest", "description": "Use the POST method to create an address. The Rapyd response provides a unique Address ID, which is required for all other operations for this address.", "method": "POST", "path": "/v1/addresses", "params": [], "body": [ { "name": "name", "type": [ { "type": "string" } ], "required": true, "description": "The name of a contact person or an \"in care of\" person at this address." }, { "name": "line_1", "type": [ { "type": "string" } ], "required": true, "description": "Line 1 of the address, such as a building number and street name." }, { "name": "line_2", "type": [ { "type": "string" } ], "required": false, "description": "Line 2 of the address, such as a suite or apartment number, or the name of a named building." }, { "name": "line_3", "type": [ { "type": "string" } ], "required": false, "description": "Line 3 of the address." }, { "name": "city", "type": [ { "type": "string" } ], "required": false, "description": "City name portion of the address. Required for issuance of a card to an eWallet contact." }, { "name": "district", "type": [ { "type": "string" } ], "required": false, "description": "Name of the district administrative subdivision, as used in banking." }, { "name": "canton", "type": [ { "type": "string" } ], "required": false, "description": "Name of the canton administrative subdivision, as used in banking." }, { "name": "state", "type": [ { "type": "string" } ], "required": false, "description": "State or province portion of the address." }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "zip", "type": [ { "type": "string" } ], "required": false, "description": "Postal code portion of the address." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number associated with this specific address in E.164 format. Must be unique." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "address-object", "id": "update-address", "type": "request", "name": "UpdateAddressRequest", "description": "Use the POST method to change or modify an address. To clear a field, set it to an empty string.", "method": "POST", "path": "/v1/addresses/{address}", "params": [ { "name": "address", "type": [ { "type": "string", "startsWith": "address_" } ], "required": true, "description": "ID of the 'address' object. String starting with **address_**." } ], "body": [ { "name": "name", "type": [ { "type": "string" } ], "required": false, "description": "The name of a contact person or an \"in care of\" person at this address." }, { "name": "line_1", "type": [ { "type": "string" } ], "required": false, "description": "Line 1 of the address, such as a building number and street name." }, { "name": "line_2", "type": [ { "type": "string" } ], "required": false, "description": "Line 2 of the address, such as a suite or apartment number, or the name of a named building." }, { "name": "line_3", "type": [ { "type": "string" } ], "required": false, "description": "Line 3 of the address." }, { "name": "city", "type": [ { "type": "string" } ], "required": false, "description": "City portion of the address. Required for issuance of a card to an eWallet contact." }, { "name": "district", "type": [ { "type": "string" } ], "required": false, "description": "Name of the district administrative subdivision, as used in banking." }, { "name": "canton", "type": [ { "type": "string" } ], "required": false, "description": "Name of the canton administrative subdivision, as used in banking." }, { "name": "state", "type": [ { "type": "string" } ], "required": false, "description": "State or province portion of the address." }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "zip", "type": [ { "type": "string" } ], "required": false, "description": "Postal code portion of the address." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number associated with this specific address in E.164 format." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "address-object", "id": "retrieve-address", "type": "request", "name": "RetrieveAddressRequest", "description": "Use the GET method to retrieve an address.", "method": "GET", "path": "/v1/addresses/{address}", "params": [ { "name": "address", "type": [ { "type": "string", "startsWith": "address_" } ], "required": true, "description": "ID of the 'address' object. String starting with **address_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "address-object", "id": "address-errors", "type": "enum", "name": "AddressError", "values": [ { "name": "ERROR_ADDRESS_GET", "description": "The request tried to retrieve an address, but the address ID was not found. The request was rejected. Corrective action: Use a valid address ID." }, { "name": "INVALID_ADDRESS_LINE_1", "description": "The request attempted an operation that requires an address, but Line 1 of the address was missing or contained special characters. The request was rejected. Corrective action: Use only alphabetic characters and spaces for 'line_1' in the 'address' object." }, { "name": "INVALID_ADDRESS_NAME", "description": "The request attempted an operation that requires an address, but the name associated with the address was missing or contained special characters. The request was rejected. Corrective action: Use only alphabetic characters and spaces for 'name' in the 'address' object." }, { "name": "INVALID_ADDRESS_PHONE_NUMBER", "description": "The request tried to add or update a phone number for an address, but the phone number is not in proper E.164 format or is not valid. The request was rejected. Corrective action: Submit the phone number in proper E.164 format." }, { "name": "INVALID_ADDRESS_ZIP", "description": "The request tried to create or update a customer's address, but the postal code was not valid. The request was rejected. Corrective action: Use the correct postal code." }, { "name": "INVALID_ADDRESSES_FORMAT", "description": "The request attempted an operation that requires an array of addresses, but the request provided a single address object. The request was rejected. Corrective action: For 'addresses', use an array of address objects." } ] }, { "product": "collect", "id": "coupon-object", "type": "type", "name": "Coupon", "description": "The Coupon object describes a discount on charges to the customer.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "coupon_" } ], "description": "Unique ID for this coupon. English alphanumeric characters with no special characters except underscore. If the merchant does not define an ID, Rapyd generates a string starting with **coupon_**. Cannot contain spaces.", "required": true }, { "name": "amount_off", "type": [ { "type": "number" } ], "description": "The amount of money to subtract from the payment. Decimal. Range: Positive decimal number, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.", "required": true }, { "name": "created", "type": [ { "type": "number" } ], "description": "When the coupon was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the `amount_off` parameter. Uppercase.\n\nRequired when `amount_off` is set.", "required": true }, { "name": "deleted", "type": [ { "type": "boolean" } ], "description": "Indicates whether the coupon has been deleted.", "required": true }, { "name": "duration", "type": [ { "type": "string", "possibleValues": [ "forever", "once", "repeating" ] } ], "description": "Determines how long the discount remains in effect. One of the following:\n* **forever**\n* **once**\n* **repeating**", "required": true }, { "name": "duration_in_months", "type": [ { "type": "number" } ], "description": "Determines the number of months that the coupon remains in effect after its creation. Integer. Relevant when `duration` is **repeating** and `redeem_by` is not set.", "required": true }, { "name": "max_redemptions", "type": [ { "type": "number" } ], "description": "Determines the number of times the coupon can be redeemed. The number of customers, subscriptions or orders that the coupon is applied to cannot exceed this number. Integer.", "required": true }, { "name": "metadata", "description": "A JSON object defined by the client.", "type": [ { "type": "object" } ], "required": true }, { "name": "percent_off", "type": [ { "type": "number" } ], "description": "Determines the size of the discount, measured in percent. Integer. Range: 1-100.", "required": true }, { "name": "redeem_by", "type": [ { "type": "number" } ], "description": "The last time at which the coupon can be redeemed, in [*Unix time*](ref:glossary). After the `redeem_by` date, the coupon can no longer be applied to new customers. 'redeem_by' takes precedence over the setting of `duration_in_months`.", "required": true }, { "name": "times_redeemed", "type": [ { "type": "number" } ], "description": "Indicates the number of times the coupon has been applied to a customer, subscription or invoice. If the discount has been used more than one time by a customer, subscription or invoice, the number of redemptions after the first is also added to this value. Integer. \n\nWhen this value equals `max_redemptions`, the coupon becomes no longer valid. Response only.", "required": true }, { "name": "valid", "type": [ { "type": "boolean" } ], "description": "Indicates whether the coupon can be redeemed.", "required": true } ] }, { "product": "collect", "parent": "coupon-object", "id": "create-coupon", "type": "request", "name": "CreateCouponRequest", "description": "Use the POST method to create a coupon.\n\nThis method triggers the **Coupon Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/coupons", "params": [], "body": [ { "name": "amount_off", "type": [ { "type": "number" } ], "required": false, "description": "The amount of money to subtract from an invoice total. This parameter is required if `percent_off` is unset." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency used in the `amount_off` parameter. Uppercase. Required when you define an amount off." }, { "name": "duration", "type": [ { "type": "string" } ], "required": true, "description": "Specifies how long the discount remains in effect: **forever**, **once** or **repeating**" }, { "name": "duration_in_months", "type": [ { "type": "string" } ], "required": false, "description": "Specifies the number of months that the coupon remains in effect after its creation. Relevant when `duration` is **repeating**." }, { "name": "id", "type": [ { "type": "string", "startsWith": "coupon_" } ], "required": false, "description": "Unique ID for this coupon. English alphanumeric characters with no special characters except underscore. If the merchant does not define an ID, Rapyd generates a string starting with **coupon_**." }, { "name": "max_redemptions", "type": [ { "type": "string" } ], "required": false, "description": "Specifies the number of instances of the coupon that can be redeemed." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "percent_off", "type": [ { "type": "number" } ], "required": false, "description": "Determines the size of the discount, measured in percent. Range: 1-100. Required when `amount_off` is 0 or null." }, { "name": "redeem_by", "type": [ { "type": "number" } ], "required": false, "description": "Date the coupon expires, in Unix time." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "coupon-object", "id": "update-coupon", "type": "request", "name": "UpdateCouponRequest", "description": "Use the POST method to change or modify the metadata of a coupon. \n\nIf you want to change anything other than the metadata, you can update the 'discount' object that is attached to a customer, subscription or order.\n\nThis method triggers the **Coupon Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/coupons/{coupon}", "params": [ { "name": "coupon", "type": [ { "type": "string" } ], "required": true, "description": "ID of the coupon." } ], "body": [ { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "coupon-object", "id": "retrieve-coupon", "type": "request", "name": "RetrieveCouponRequest", "description": "Use the GET method to retrieve a coupon.", "method": "GET", "path": "/v1/coupons/{coupon}", "params": [ { "name": "coupon", "type": [ { "type": "string" } ], "required": true, "description": "ID of the coupon." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "coupon-object", "id": "list-coupons", "type": "request", "name": "ListCouponsRequest", "description": "Use the GET method to retrieve a list of all coupons.", "method": "GET", "path": "/v1/coupons", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the coupon created after the last coupon you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of coupons to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the coupon created before the first coupon you want to retrieve." } ] }, { "product": "collect", "parent": "coupon-object", "id": "delete-coupon", "type": "request", "name": "DeleteCouponRequest", "description": "Use the DELETE method to delete a coupon from the Rapyd platform. Deleting a coupon removes it from all customers and subscriptions, but does not affect invoices and payment authorizations that have already been calculated.\n\nThis method triggers the **Coupon Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/coupons/{coupon}", "params": [ { "name": "coupon", "type": [ { "type": "string" } ], "required": true, "description": "ID of the coupon." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "coupon-object", "id": "coupon-errors", "type": "enum", "name": "CouponError", "values": [ { "name": "ERROR_COUPON_DISCOUNT_NOT_RECOGNIZED", "description": "The request tried to create a coupon, but the discount was set by both percentage and fixed amount. The request was rejected. Corrective action: Set 'percent_off' or set 'amount_off' and 'currency'." }, { "name": "ERROR_DELETE_COUPON", "description": "The request tried to delete a coupon, but the operation failed. Corrective action: Determine whether the coupon was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_COUPON", "description": "The request attempted an operation that requires the ID of a coupon, but the coupon was not found. The request was rejected. Corrective action: Use the ID of a valid coupon." }, { "name": "ERROR_GET_DISCOUNT", "description": "The request attempted an operation that requires the ID of a coupon, but the coupon was not found. The request was rejected. Corrective action: Use the ID of a valid coupon." }, { "name": "INVALID_AMOUNT_OFF_AND_CURRENCY", "description": "The request tried to create a coupon, but 'amount_off' was set and 'currency' was unset or invalid. The request was rejected. Corrective action: Use the correct 3-letter ISO 4217 code for the currency, in uppercase letters." }, { "name": "INVALID_COUPON_AMOUNT_OFF", "description": "The request tried to create a coupon, but the amount off was not a positive number. The request was rejected. Corrective action: Use a positive decimal value for 'percent_off'." }, { "name": "INVALID_COUPON_DURATION", "description": "The request tried to create a coupon, but the value for the 'duration' parameter was not recognized. The request was rejected. Corrective action: Set 'duration' to one of the following values: 'forever', 'once', 'repeating'" }, { "name": "INVALID_COUPON_LIMIT", "description": "The request tried to retrieve a list of coupons, but the 'limit' query parameter was out of range. The request was rejected. Corrective action: Set 'limit' to an integer between 10 and 100." }, { "name": "INVALID_COUPON_PERCENT_OFF", "description": "The request tried to create a coupon, but the percent off was less than 1 or greater than 100. The request was rejected. Corrective action: Set 'percent_off' to an integer between 0-100." }, { "name": "INVALID_COUPON_PERCENT_AND_AMOUNT_OFF", "description": "The request tried to create a coupon, but the type of discount could not be determined. The request was rejected. Corrective action: Set 'percent_off' or set 'amount_off' and 'currency'." }, { "name": "INVALID_PERCENT_OFF", "description": "The request tried to create a coupon, but the percent off was less than 1 or greater than 100. The request was rejected. Corrective action: Use an integer value between 0-100 for 'percent_off'." } ] }, { "product": "collect", "id": "product-object-collect", "type": "type", "name": "Product", "description": "The Product object describes a single product or service.", "fields": [ { "description": "Unique string for identification of the product. Legal input includes alphanumeric characters and the underscore (_) character. If the merchant does not define an ID, Rapyd generates it with a string that starts with **product_**.", "type": [ { "type": "string" } ], "name": "id", "required": true }, { "name": "active", "type": [ { "type": "boolean" } ], "description": "Indicates whether the product is currently available for purchase.", "required": true }, { "name": "attributes", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "Up to 5 unique alphanumeric strings defined by the merchant. Cannot contain spaces. For example:\n\n[\n\n> \"size\",\n> \"color\"\n\n]\n\nEach string defines the key in a key-value pair in the 'attributes' object in the corresponding 'sku' objects.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of this product, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Full text description of the product.", "required": true }, { "name": "images", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Images associated with the product.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "name", "type": [ { "type": "string" } ], "description": "The name of the product or service that appears in the line items in invoices.", "required": true }, { "name": "package_dimensions", "type": [ { "type": "object", "fields": [ { "name": "height", "type": [ { "type": "unknown" } ] }, { "name": "length", "type": [ { "type": "unknown" } ] }, { "name": "weight", "type": [ { "type": "unknown" } ] }, { "name": "width", "type": [ { "type": "unknown" } ] } ] } ], "description": "Describes the physical size and weight of the product. Contains the following fields:\n\\* `height`\n\\* `length`\n\\* `weight`\n\\* `width`\n\nThese fields are represented as numbers, but it is the responsibility of the merchant to define and interpret the relevant units of length and weight.", "required": true }, { "name": "shippable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the product can be shipped.", "required": true }, { "name": "skus", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "sku-object" } ] } ], "description": "An array of SKUs associated with this product. Relevant when `type` is **goods**. Read-only.\n\nTo add SKUs to a product, use [Create SKU](ref:create-sku). For more information, see [SKU Object](ref:sku-object).", "required": true }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "description": "Description that is suitable for a customer's statement. Limited to 22 characters.\n\nRelevant when `type` is **service**. Must be null when `type` is **goods**.", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "services", "goods" ] } ], "description": "One of the following: \n\\* **services** - Relevant to subscriptions and plans.\n\\* **goods** - Relevant to orders and SKUs.", "required": true }, { "name": "unit_label", "type": [ { "type": "string" } ], "description": "Determines what one unit of this product is called on customers’ receipts and invoices, such as minutes, viewings, kilometers or packages.\n\nRelevant when `type` is **service**. Must be null when `type` is **goods**.", "required": true }, { "name": "updated_at", "type": [ { "type": "number" } ], "description": "Time that this product was last updated, in [*Unix time*](ref:glossary). Response only.", "required": true } ] }, { "product": "collect", "parent": "product-object-collect", "id": "create-product", "type": "request", "name": "CreateProductRequest", "description": "Use the POST method to create goods or services. If the product is goods, use [Create SKU](ref:create-sku) to add a SKU to the product.\n\nThis method triggers the **Product Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/products", "params": [], "body": [ { "name": "active", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the product is currently available for purchase. Default is true." }, { "name": "attributes", "type": [ { "type": "string" } ], "required": false, "description": "Array of up to 5 alphanumeric strings defined by the merchant. Each string defines the key in a key-value pair in the 'attributes' object in the corresponding 'sku' objects." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Full text description of the product." }, { "name": "id", "type": [ { "type": "string" } ], "required": false, "description": "Unique string for identification of the product. Legal input includes all the English alphanumeric characters and the underscore (_) character. If the merchant does not define an ID, Rapyd generates it with a string that starts with **product\\_**." }, { "name": "images", "type": [ { "type": "string" } ], "required": false, "description": "An array of images. Each image is a string in Base64 encoding." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "name", "type": [ { "type": "string" } ], "required": true, "description": "The name of the product or service that is displayed to the customer." }, { "name": "package_dimensions", "type": [ { "type": "object" } ], "required": false, "description": "Describes the physical size and weight of the product. Relevant when `type` is *goods*. Contains the following fields: `height` `length` `weight` `width`" }, { "name": "shippable", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the product is physically shipped to the customer. Relevant when `type` is **goods**. Default is *false*." }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "A text description that appears in the customer's invoice. Limited to 22 characters. Relevant when `type` is **service**." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "One of the following: **services**, **goods**" }, { "name": "unit_label", "type": [ { "type": "string" } ], "required": false, "description": "A label that represents units of this product, such as seats, on customers’ invoices. Relevant when `type` is **service**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "product-object-collect", "id": "update-product", "type": "request", "name": "UpdateProductRequest", "description": "Use the POST method to change or modify a product or service.\n\nThis method triggers the **Product Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/products/{product}", "params": [ { "name": "product", "type": [ { "type": "string" } ], "required": true, "description": "ID of the product." } ], "body": [ { "name": "active", "type": [ { "type": "boolean" } ], "required": false, "description": "Indicates whether the product is currently available for purchase." }, { "name": "attributes", "type": [ { "type": "string" } ], "required": false, "description": "Array of up to 5 alphanumeric strings defined by the merchant. Each string defines the key in a key-value pair in the 'attributes' object in the corresponding 'sku' objects." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "name", "type": [ { "type": "string" } ], "required": false, "description": "The name of the product or service that is displayed to the customer." }, { "name": "package_dimensions", "type": [ { "type": "string" } ], "required": false, "description": "Describes the physical size and weight of the product. Relevant when `type` is *goods*. Contains the following fields: `height` `length` `weight` `width`" }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "A text description that appears in the customer's invoice. Limited to 22 characters. Relevant when `type` is **service**. Must be null when `type` is **goods**." }, { "name": "unit_label", "type": [ { "type": "string" } ], "required": false, "description": "A label that represents units of this product, such as seats, in Rapyd and on customers’ receipts and invoices. Relevant when `type` is **service**. Must be null when `type` is **goods**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "product-object-collect", "id": "retrieve-product", "type": "request", "name": "RetrieveProductRequest", "description": "Use the GET method to retrieve details of a product or service.", "method": "GET", "path": "/v1/products/{product}", "params": [ { "name": "product", "type": [ { "type": "string" } ], "required": true, "description": "ID of the product." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "product-object-collect", "id": "list-products", "type": "request", "name": "ListProductsRequest", "description": "Use the GET method to retrieve a list of all products. Use the optional query parameters to filter the results. You can filter the results further by specifying one or more Product fields as additional query parameters.", "method": "GET", "path": "/v1/products", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the product created after the last product you want to retrieve." }, { "name": "limit", "type": [ { "type": "number" } ], "required": false, "description": "The maximum number of products to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the product created before the first product you want to retrieve." } ] }, { "product": "collect", "parent": "product-object-collect", "id": "delete-product", "type": "request", "name": "DeleteProductRequest", "description": "Use the DELETE method to delete a product or service from the Rapyd platform.\n\nThis method triggers the **Product Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/products/{product}", "params": [ { "name": "product", "type": [ { "type": "string" } ], "required": true, "description": "ID of the product." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "product-object-collect", "id": "product-errors", "type": "enum", "name": "ProductError", "values": [ { "name": "ERROR_CREATE_PRODUCT_DUPLICATE_PRODUCT_ID", "description": "The request tried to validate identity, but the 'id' body parameter was previously used. The request was rejected. Corrective action: Provide a unique product ID for each identity verification operation, whether successful or unsuccessful." }, { "name": "ERROR_CREATE_SERVICE_PACKAGE_DIMENSIONS_NOT_ALLOWED", "description": "The request tried to create a product of type 'service', but package dimensions were specified. The request was rejected. Corrective action: Set 'package_dimensions' to null." }, { "name": "ERROR_DELETE_PRODUCT", "description": "The request tried to delete a product, but the product was not found. The request was rejected. Corrective action: Determine whether the product was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_PRODUCT", "description": "The request tried to retrieve a product, but the product was not found. The request was rejected. Corrective action: Use a valid product ID." }, { "name": "ERROR_PRODUCT_ATTRIBUTE_MUST_BE_STRING", "description": "The request tried to create a product, but the 'attributes' field was not an array of strings. The request was rejected. Corrective action: Use an array of strings." }, { "name": "ERROR_SHIPPING_NOT_ALLOWED_FOR_PRODUCT_TYPE_SERVICE", "description": "The request tried to create a product of type 'service', but the 'shippable' field was set to 'true'. The request was rejected. Corrective action: Set 'shippable' to null or 'false'." }, { "name": "INVALID_PARAMETER_STATEMENT_DESCRIPTOR_MUST_BE_EMPTY", "description": "The request tried to create a product of type 'goods', but the statement descriptor was set. The request was rejected. Corrective action: Set 'statement_descriptor' to null." }, { "name": "INVALID_PARAMETER_UNIT_LABEL_MUST_BE_EMPTY", "description": "The request tried to create a product of type='goods', but the 'unit_label' field contained a value. The request was rejected. Corrective action: Use an empty string." }, { "name": "INVALID_PRODUCT", "description": "The request tried to perform an operation that requires a product, but the product was not found. The request was rejected. Corrective action: Use a valid product ID." }, { "name": "INVALID_PRODUCT_ATTRIBUTES", "description": "The request tried to create or update a product, but the 'attributes' body parameter was not found or is not an array. The request was rejected. Corrective action: Define the 'attributes' body parameter as an array." }, { "name": "INVALID_PRODUCT_ATTRIBUTES_LIMIT", "description": "The request tried to create or update a product, but the 'attributes' array contained more than 5 elements. The request was rejected. Corrective action: Define the 'attributes' body parameter as an array of zero to five strings." }, { "name": "INVALID_PRODUCT_IMAGES", "description": "The request tried to create a product, but the 'images' body parameter was not an array. The request was rejected. Corrective action: Define the 'images' body parameter as an array." }, { "name": "INVALID_PRODUCT_NAME", "description": "The request tried to create a product, but the 'name' body parameter was empty or not found. The request was rejected. Corrective action: Define the 'name' body parameter." }, { "name": "INVALID_PRODUCT_TYPE", "description": "The request tried to create a product, but the value for the 'type' body parameter was not recognized. The request was rejected. Corrective action: Define the 'type' body parameter as 'service' or 'goods'." }, { "name": "INVALID_STATEMENT_DESCRIPTOR", "description": "The request attempted an operation that uses a statement descriptor, but it contained illegal characters. The request was rejected. Corrective action: For the 'statement_descriptor' body parameter, use a string of 1-22 alphanumeric characters and spaces." } ] }, { "product": "collect", "id": "customer-payment-method-object", "type": "type", "name": "CustomerPaymentMethod", "description": "The customer payment method object describes one of the payment methods of the customer that has been saved to the Customer object and is now on file.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "ID of the Payment Method object. String starting with **card_** or *other_**.", "required": true }, { "name": "acs_check", "type": [ { "type": "string", "possibleValues": [ "pass", "fail", "unavailable", "unchecked" ] } ], "description": "Results of the ACS check. Read-only. Possible values:\n* **pass**\n* **fail**\n* **unavailable**\n* **unchecked**\n\nRelevant to cards.", "required": true }, { "name": "avs_check", "type": [ { "type": "string" } ], "description": "Results of the Address Verification Service (AVS) check. Relevant to Visa, Mastercard, Amex, and Discover cards.", "required": true }, { "name": "address", "type": [ { "type": "object", "id": "address-object" } ], "description": "Address object. For details, see [Address Object](ref:address-object).", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer, a string starting with **cus_**.", "required": true }, { "name": "cvv_check", "description": "Results of the CVV check. Read-only. Possible values:\n* **pass**\n* **fail**\n* **unavailable**\n* **unchecked**\n\nRelevant to cards.", "type": [ { "type": "string", "possibleValues": [ "pass", "fail", "unavailable", "unchecked" ] } ], "required": true }, { "name": "ending_before", "type": [ { "type": "string" } ], "description": "The ID of the payment method created after the last payment method you want to retrieve.", "required": true }, { "name": "fields", "type": [ { "type": "object", "id": "retrieve-payment-method-required-fields" } ], "description": "Contains the fields that are required for the specific payment method.\n\nTo determine what fields are required for the payment method, see [Get Payment Method Required Fields](ref:retrieve-payment-method-required-fields).", "required": true }, { "name": "limit", "type": [ { "type": "string" } ], "description": "The maximum number of payment methods to return. Range: 1-100. Default is 10.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "ID of the payment method to update. String starting with **card_** or **other_**.", "required": true }, { "name": "starting_after", "type": [ { "type": "string" } ], "description": "The ID of the payment method created before the first payment method you want to retrieve.", "required": true }, { "name": "token", "type": [ { "type": "string" } ], "description": "ID of the token that represents the card. Relevant to cards.\n\nFor more information, see [Token Object for Card](ref:token-object-for-card).", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Name of the payment method type. For example, **us_mastercard_card**.\n\nTo get a list of payment methods for a country, use [List Payment Methods by Country](/build-with-rapyd/reference/payment-method-type-object#list-payment-methods-by-country).", "required": true } ] }, { "product": "collect", "parent": "customer-payment-method-object", "id": "add-payment-method-to-customer", "type": "request", "name": "AddPaymentMethodToCustomerRequest", "description": "Use the POST method to add a payment method to a customer. Use the appropriate set of required fields. For a card, you can also use the card ID.\n\nUse the [Get Payment Method Required Fields](ref:get-payment-method-required-fields) method to determine which fields are required to create the payment method. The response to this request contains the payment method ID that you can use to create a subscription or payment.\n\nFor adding card by ID, both `type` and `token` parameters are required. Use a [Create Token](ref:create-token) request for a card token to get the card token.\n\nThis method triggers the **Customer Payment Method Created** webhook. This webhook contains the same information as the response.\n\nThe following asynchronous webhook provides information about later changes to the Payment Method object:\n\n* [Webhook - Payment Method Failed](ref:webhook-payment-method-failed) \n\n> **Note:** Merchants who have PCI clearance and who have signed a special agreement with Rapyd can add a card payment method.", "method": "POST", "path": "/v1/customers/{customer}/payment_methods", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the customer. String starting with **cus_**." } ], "body": [ { "name": "address", "type": [ { "type": "string" } ], "required": false, "description": "'address' object. For details, see [Address Object](ref:address-object)." }, { "name": "fields", "type": [ { "type": "string" } ], "required": false, "description": "Object that contains the fields that are required for the specific payment method. Required if the `token` field is not used. See [Get Payment Method Required Fields](ref:get-payment-method-required-fields)." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "token", "type": [ { "type": "string", "startsWith": "card_" } ], "required": false, "description": "ID of the payment method. String starting with **card_** or **other_**. Required when the `type` field and the `fields` object are not used." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "Name of the payment method. Required when `token` is not used." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-payment-method-object", "id": "update-payment-method", "type": "request", "name": "UpdatePaymentMethodRequest", "description": "Use POST to change or modify a payment method. Other fields might be required, as shown by [Get Payment Method Required Fields](ref:retrieve-payment-method-required-fields).\n\n> **Note:** If this method is used to update one of the fields of the 'fields' object in a card, the payment method ID is replaced with a new value.\n\n> You must provide all required fields of the 'address' object. If you change the expiration date, you must update both the month and year. If you try to change the card number or CVV, the update request fails.\n\nThis method triggers the **Customer Payment Method Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/customers/{customer}/payment_methods/{payment_method}", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." }, { "name": "payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the payment method to update. String starting with **card_** or **other_**." } ], "body": [ { "name": "address", "type": [ { "type": "string" } ], "required": false, "description": "'address' object. For details, see [Address Object](ref:address-object)." }, { "name": "fields", "type": [ { "type": "string" } ], "required": false, "description": "Contains the fields that are required for the specific payment method. See [Get Payment Method Required Fields](ref:retrieve-payment-method-required-fields). To determine what fields can be updated, see the 'payment_options' field in the response to [List Payment Methods by Country](ref:retrieve-all-payment-methods-by-country)." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-payment-method-object", "id": "retrieve-payment-method", "type": "request", "name": "RetrievePaymentMethodRequest", "description": "Use GET to retrieve a payment method for a specific customer. You can retrieve all of the customer's payment methods by omitting the 'payment_method_id' path parameter.", "method": "GET", "path": "/v1/customers/{customer}/payment_methods/{payment_method}", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." }, { "name": "payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the payment method to retrieve. String starting with **card_** or **other_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-payment-method-object", "id": "list-payment-methods-of-customer", "type": "request", "name": "ListPaymentMethodsOfCustomerRequest", "description": "Use the GET method to list all the payment methods of a customer.", "method": "GET", "path": "/v1/customers/{customer}/payment_methods", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." } ], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the payment method created after the last payment method you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of payment methods to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the payment method created before the first payment method you want to retrieve." }, { "name": "type", "type": [ { "type": "string" } ], "required": false, "description": "The type of payment method to find." } ] }, { "product": "collect", "parent": "customer-payment-method-object", "id": "delete-payment-method", "type": "request", "name": "DeletePaymentMethodRequest", "description": "Use DELETE to delete a payment method from a customer.\n\nThis method triggers the **Payment Method Canceled** webhook. This webhook contains more information than the response.", "method": "DELETE", "path": "/v1/customers/{customer}/payment_methods/{payment_method}", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." }, { "name": "payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "required": true, "description": "ID of the payment method to delete. String starting with **card_** or **other_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-payment-method-object", "id": "customer-payment-method-errors", "type": "enum", "name": "CustomerPaymentMethodError", "values": [ { "name": "CREATE_CARD_TYPE_REQUIRES_ONLY_ONE_OF_FIELDS_OR_TOKEN", "description": "The request tried to add a payment method to a customer, but both the 'type' and 'token' body parameters are set, or they are both unset. The request was rejected. Corrective action: Set one of the following parameters: 'type' or 'token'." }, { "name": "ERROR_CREATE_PAYMENT_METHOD", "description": "The request attempted an operation that requires specific fields for payment method, but a required field was missing, or an extra, unallowed field was included. Corrective action: Run 'Get Payment Method Required Fields' and check all input fields." }, { "name": "ERROR_DELETE_PAYMENT_METHOD_FROM_WRONG_CUSTOMER", "description": "The request tried to delete a payment method from a customer, but the payment method was not assigned to the customer that was specified in the request. The request was rejected. Corrective action: Indicate a payment method that is on the current list of payment methods for the designated customer." }, { "name": "ERROR_GET_CUSTOMER_DEFAULT_PAYMENT_METHOD", "description": "The request attempted an operation that requires a customer's default payment method, but the default payment method was not found. The request was rejected. Corrective action: Use 'Update Customer' to set the default payment method." }, { "name": "ERROR_GET_PAYMENT_METHOD_TYPE", "description": "The request attempted an operation that requires a payment method, but the payment method type was not recognized or is not available for this merchant. Corrective action: For the 'type' field in the 'payment_method' object or in the 'data' object, use a payment method type that this merchant is authorized to use, or contact Client Support." }, { "name": "PAYMENT_METHOD_FIELD_NOT_UPDATABLE", "description": "The request tried to update a payment method of a customer, but it tried to set a new value for a field that does not exist or is not modifiable. The request was rejected. Corrective action: Do not change the value of the field named at the end of the error code." }, { "name": "PAYMENT_METHOD_REQUIRES_ONLY_ONE_OF_TYPE_OR_TOKEN", "description": "The request tried to add a payment method to a customer, but both the 'type' and 'token' body parameters are set, or they are both unset. The request was rejected. Corrective action: Set one of the following parameters: 'type' or 'token'." } ] }, { "product": "issuing", "id": "card-details-object", "type": "type", "name": "CardDetails", "description": "The Card Details object contains information about a virtual card that you can display to your customer. You can customize the card appearance.", "fields": [ { "name": "id", "type": [ { "type": "string" } ], "description": "The ID of the hosted page. String starting with **hp\\_issued\\_**.\nResponse only.", "required": true }, { "name": "card", "type": [ { "type": "string (Request)\nobject (Response)" } ], "description": "In the request, the ID of the issued card, a string starting with **ci_** or **card_**.\n\nIn the response, an object containing the following fields:\n\\* `name` - The name of the person that the card is issued to.\n\\* `network` - The card network of the issued card.", "required": true }, { "name": "card_color", "type": [ { "type": "string" } ], "description": "The color of the card, specified by one of the following:\n\\* hexadecimal value\n\\* RGB\n\\* RGBA\n\\* CSS color name \nThe default is **black**.", "required": true }, { "name": "expiration", "description": "Time when the page URL expires, in [*Unix time*](ref:glossary). 5 minutes from creation of the page.\nResponse only.", "type": [ { "type": "number" } ], "required": true }, { "description": "Determines the default language of the hosted page. \nThe values are listed on [Hosted Page Language Support](ref:hosted-page-language-support).", "name": "language", "type": [ { "type": "string" } ], "required": true }, { "name": "logo", "type": [ { "type": "string" } ], "description": "The URL of the logo image that appears on the card. If the logo is not specified, the name of the merchant appears.", "required": true }, { "name": "logo_orientation", "type": [ { "type": "string", "possibleValues": [ "landscape", "square", "portrait" ] } ], "description": "The orientation of the logo. One of the following:\n\\* **landscape** - This is the default. \n\\* **square**\n\\* **portrait**", "required": true }, { "name": "merchant_alias", "type": [ { "type": "string" } ], "description": "The name that appears in the card image if nothing is specified for `logo`. To change this value, contact [Client Support](doc:client-support).\nResponse only.", "required": true }, { "name": "merchant_color", "description": "Color for the client's website, defined in the Client Portal.\nResponse only.", "type": [ { "type": "string" } ], "required": true }, { "name": "merchant_customer_support", "type": [ { "type": "object", "fields": [ { "name": "email", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] }, { "name": "phone_number", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contact details for customer support, containing the following fields:\n\\* `email` - Email address.\n\\* `url` - URL for the client's customer support service.\n\\* `phone_number` - Phone number for contacting the client's customer support service.\n\nTo configure these fields, use the Client Portal.\n\nResponse only.", "required": true }, { "name": "merchant_language", "description": "Language of the displayed page.\n\nResponse only.", "type": [ { "type": "string" } ], "required": true }, { "name": "merchant_logo", "description": "URL for the image of the client's logo.\n\nResponse only.", "type": [ { "type": "string" } ], "required": true }, { "name": "merchant_website", "description": "URL of the client's website.\nResponse only.", "type": [ { "type": "string" } ], "required": true }, { "name": "redirect_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected to view an image of the card.\n\nResponse only.", "required": true }, { "name": "status", "description": "Reserved.\nResponse only.", "type": [ { "type": "string" } ], "required": true } ] }, { "product": "issuing", "parent": "card-details-object", "id": "display-issued-card-details-to-customer", "type": "request", "name": "DisplayIssuedCardDetailsToCustomerRequest", "description": "Use the POST method to generate a hosted page that displays details of a virtual issued card directly to the customer. The URL is available for 5 minutes after the response is sent, then it expires.", "method": "POST", "path": "/v1/hosted/issuing/card_details/{card}", "params": [ { "name": "card", "type": [ { "type": "string", "startsWith": "ci_" } ], "required": true, "description": "ID of the issued card, a string starting with **ci_** or **card_**." } ], "body": [ { "name": "card_color", "type": [ { "type": "string" } ], "required": false, "description": "The color of the card, specified by hexadecimal value, CSS color name, RGB, or RGBA." }, { "name": "language", "type": [ { "type": "string" } ], "required": false, "description": "Determines the default language of the hosted page." }, { "name": "logo", "type": [ { "type": "string" } ], "required": false, "description": "The URL of the logo image displayed on the card." }, { "name": "logo_orientation", "type": [ { "type": "string" } ], "required": false, "description": "The orientation of the logo on the card." } ], "headers": [], "query": [] }, { "product": "collect", "id": "customer-object", "type": "type", "name": "Customer", "description": "The Customer object describes the person or company that pays for products and services. It is a profile where the payer's payment methods are stored for future use. One payment method can be selected as the default.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the Customer object. String starting with **cus_**.", "required": true }, { "name": "address", "type": [ { "type": "object", "id": "address-object" } ], "description": "Address object. For details, see [Address Object](ref:address-object).", "required": true }, { "name": "addresses", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Describes the addresses associated with this customer.\n\nFor more information, see [Address Object](#address-object).", "required": true }, { "name": "business_vat_id", "type": [ { "type": "string" } ], "description": "The tax ID number of the customer. Relevant when the customer is a business.", "required": true }, { "name": "category", "type": [ { "type": "string", "possibleValues": [ "bank_redirect", "bank_transfer", "card", "cash", "ewallet", "rapyd_ewallet" ] } ], "description": "Category of payment method. Possible values:\n* **bank_redirect**\n* **bank_transfer**\n* **card**\n* **cash**\n* **ewallet**\n* **rapyd_ewallet**\n\nResponse only.", "required": true }, { "name": "coupon", "type": [ { "type": "string" } ], "description": "The ID of a discount coupon that is assigned to this customer. The coupon must use the same currency as the customer's default payment method.\n\nFor more information, see [Coupon Object](#coupon-object).", "required": true }, { "type": [ { "type": "number" } ], "name": "created_at", "description": "Time of creation of this customer, in [*Unix time*](ref:glossary).\n\nResponse only.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer, a string starting with **cus_**.", "required": true }, { "name": "default_payment_method", "type": [ { "type": "string" }, { "type": "object" } ], "description": "The payment method that is used when the 'payment' object or subscription does not specify a payment method. Must appear in the `payment_methods` list. The payment method is referenced by its `name` field.", "required": true }, { "name": "delinquent", "type": [ { "type": "boolean" } ], "description": "Indicates whether there is currently a failure of an automatic payment that is part of a subscription, or an invoice that was not paid when due.\n* **true**: The account is delinquent.\n* **false**: The account is current.\n\nResponse only.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "A text description of the customer.", "required": true }, { "name": "discount", "description": "Contains information about the coupon that applies to the customer. Read-only field.\n\nAdding a discount is a 2-step process:\n1. [Create Coupon](ref:create-coupon), which returns a coupon ID. \n2. Add the coupon ID to the `coupon` field of the customer with [Create Customer](ref:create-customer) or [Update Customer](ref:update-customer).\n\nFor more information, see [Discount Object](ref:discount-object).", "type": [ { "type": "object", "id": "discount-object" } ], "required": true }, { "name": "email", "type": [ { "type": "string" } ], "description": "Customer's email address. Maximum 512 characters.", "required": true }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that is linked to the customer. String starting with **ewallet_**.\n\nEach wallet can be associated with only one customer.", "required": true }, { "name": "fields", "type": [ { "type": "object", "id": "retrieve-payment-method-required-fields" } ], "description": "Contains the fields that are required for the specific payment method.\n\nTo determine what fields are required for the payment method, see [Get Payment Method Required Fields](ref:retrieve-payment-method-required-fields).", "required": true }, { "name": "invoice_prefix", "type": [ { "type": "string" } ], "description": "A custom string that is prefixed to all invoices for this customer. For more information, see [Invoice Object](ref:invoice-object).", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "name", "type": [ { "type": "string" } ], "description": "The name of the customer.\n* Business - The company name.\n* Individual - The person's name.", "required": true }, { "name": "payment_methods", "type": [ { "type": "object", "fields": [ { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ], "id": "payment-method-object" } ], "description": "An object containing the following fields:\n* `data` - A list of up to three payment methods. See [Payment Method Object](ref:payment-method-object).\n* `has_more` - Indicates whether there are more than three payment methods for this customer.\n* `total_count` - Total number of payment methods for this customer.\n* `url` - URL for requesting all of the payment methods for this customer.\n\n**Note:** You cannot delete a payment method that is the designated default payment method.\n\nYou can include a payment method when you create the customer using [Create Customer](ref:create-customer), or you can add it later with [Add Payment Method to Customer](ref:add-payment-method-to-customer).", "required": true }, { "name": "phone_number", "type": [ { "type": "string" } ], "description": "Customer's primary phone number in E.164 format. The merchant is responsible for verifying that the number is correct. One method of verifying could be to send an activation code to the phone by SMS, with a limited time for response.", "required": true }, { "name": "subscriptions", "type": [ { "type": "object", "fields": [ { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ], "id": "subscription-object" } ], "description": "An object containing the following fields:\n* `data` - A list of up to three subscriptions.\n* `has_more` - Indicates whether there are more than three subscriptions for this customer.\n* `total_count` - Total number of subscriptions for this customer.\n* `url` - URL for requesting all of the subscriptions for this customer.\n\nTo add a subscription to a customer, use [Create Subscription](ref:create-subscription). For more information, see [Subscription Object](ref:subscription-object)", "required": true }, { "name": "token", "type": [ { "type": "string" } ], "description": "ID of the token that represents the card. Relevant to cards.\n\nFor more information, see [Token Object for Card](ref:token-object-for-card).", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "Name of the payment method type. For example, **us_mastercard_card**.\n\nTo get a list of payment methods for a country, use [List Payment Methods by Country](ref:list-payment-methods-by-country).", "required": true } ] }, { "product": "collect", "parent": "customer-object", "id": "create-customer", "type": "request", "name": "CreateCustomerRequest", "description": "Use the POST method to create a customer. The Rapyd response provides a unique Customer ID, which is required for all other operations for this customer.\n\nUse [Add Payment Method](ref:add-payment-method) to add payment methods. Use [Update Customer](ref:update-customer) to set the customer's default payment method. \n\nThis method triggers the **Customer Created** webhook. This webhook contains the same information as the response.\n\n> **Note:** If the customer has more than one address, use 'Create Customer' to add the primary address and 'Update Customer' to add more addresses.", "method": "POST", "path": "/v1/customers", "params": [], "body": [ { "name": "addresses", "type": [ { "type": "string" } ], "required": false, "description": "Array of address objects associated with this customer. For more information, see [Address Object](ref:address-object)." }, { "name": "business_vat_id", "type": [ { "type": "string" } ], "required": false, "description": "The tax ID number of the customer." }, { "name": "coupon", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a coupon that is assigned to this customer." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "A text description of the customer." }, { "name": "email", "type": [ { "type": "string" } ], "required": false, "description": "Customer's email address. Required for some payment methods." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the wallet that is linked to the customer. String starting with **ewallet_**. Each wallet can be associated with only one customer." }, { "name": "invoice_prefix", "type": [ { "type": "string" } ], "required": false, "description": "A custom string that is prefixed to all invoices for this customer." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "name", "type": [ { "type": "string" } ], "required": true, "description": "The name of the individual customer or the business name." }, { "name": "payment_method", "type": [ { "type": "string" } ], "required": false, "description": "An object that contains the following parameters: 'type', 'fields', 'metadata'" }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Customer's primary phone number in E.164 format." }, { "name": "type", "type": [ { "type": "string" } ], "required": false, "description": "" } ], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-object", "id": "update-customer", "type": "request", "name": "UpdateCustomerRequest", "description": "Use the POST method to change one or more fields in a 'customer' object. To clear a field, set it to an empty string.\n\nThis method triggers the **Customer Updated** webhook. This webhook contains the same information as the response.\n\nWhen this method is used to add a discount to a customer, it triggers the **Customer Discount Created** webhook.", "method": "POST", "path": "/v1/customers/{customer}", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." } ], "body": [ { "name": "addresses", "type": [ { "type": "string" } ], "required": false, "description": "Array of address objects associated with this customer. For more information, see [Address Object](ref:#address-object)." }, { "name": "business_vat_id", "type": [ { "type": "string" } ], "required": false, "description": "The tax ID number of the customer." }, { "name": "coupon", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a coupon that is assigned to this customer." }, { "name": "default_payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "required": false, "description": "The payment method that is used when the transaction does not specify a payment method. String starting with **card_** or **other_**. Must appear in the array in the `payment_methods` field." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "A text description of the customer." }, { "name": "email", "type": [ { "type": "string" } ], "required": false, "description": "Customer's email address." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the wallet that is linked to the customer. String starting with **ewallet_**." }, { "name": "invoice_prefix", "type": [ { "type": "string" } ], "required": false, "description": "A custom string that is prefixed to all invoices for this customer." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the Rapyd partner." }, { "name": "name", "type": [ { "type": "string" } ], "required": false, "description": "The name of the individual customer or the business name." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Customer's primary phone number in E.164 format." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-object", "id": "list-customers", "type": "request", "name": "ListCustomersRequest", "description": "Use the GET method to retrieve a list of all customers.", "method": "GET", "path": "/v1/customers", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "The ID of the customer created after the last customer you want to retrieve. String starting with **cus_**." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of customers to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "The ID of the customer created before the first customer you want to retrieve. String starting with **cus_**." } ] }, { "product": "collect", "parent": "customer-object", "id": "retrieve-customer", "type": "request", "name": "RetrieveCustomerRequest", "description": "Use the GET method to retrieve details of a customer.", "method": "GET", "path": "/v1/customers/{customer}", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-object", "id": "delete-customer", "type": "request", "name": "DeleteCustomerRequest", "description": "Use the DELETE method to delete a customer.\n\nThis method triggers the **Customer Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/customers/{customer}", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-object", "id": "delete-discount-from-customer", "type": "request", "name": "DeleteDiscountFromCustomerRequest", "description": "Use the DELETE method to delete the discount that has been assigned to a customer through a coupon. This action does not affect the coupon that the discount was derived from.\n\nThis method triggers the **Customer Discount Deleted** webhook.", "method": "DELETE", "path": "/v1/customers/{customer}/discount", "params": [ { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the 'customer' object. String starting with **cus_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "customer-object", "id": "customer-errors", "type": "enum", "name": "CustomerError", "values": [ { "name": "CREDIT_CARD_EXISTS", "description": "The request tried to add a credit card to a customer, but the customer already has this card as a payment method. The request was rejected. Corrective action: None. Determine why an attempt was made to add the same card twice." }, { "name": "CUSTOMER_ALREADY_ASSIGNED_TO_EWALLET", "description": "The request tried to add a wallet to a customer, but the customer already has a wallet. The request was rejected. Corrective action: Create a new customer and add the wallet to the new customer." }, { "name": "DELETE_CUSTOMER_DEFAULT_PAYMENT_METHOD_NOT_ALLOWED", "description": "The request tried to delete the default payment method from a customer, but this operation is not allowed. The request was rejected. Corrective action: Assign another payment method to be the default payment method, then repeat the delete request." }, { "name": "ERROR_CREATE_CUSTOMER", "description": "The request tried to create or update a customer, but the wallet ID provided is already in use by another customer. The request was rejected. Corrective action: Create a new wallet." }, { "name": "ERROR_DEFAULT_PAYMENT_METHOD_BELONGS_TO_DIFFERENT_CUSTOMER", "description": "The request tried to update a customer, but the proposed default payment method belongs to a different customer. The request was rejected. Corrective action: For 'default_payment_method', use a payment method that belongs to the customer you want to update." }, { "name": "ERROR_DELETE_CUSTOMER", "description": "The request tried to delete a customer, but the operation failed. Corrective action: Determine whether the customer was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_DELETE_CUSTOMER_DISCOUNT", "description": "The request tried to delete a discount from a customer, but the operation failed. Corrective action: Determine whether the discount was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_CUSTOMER", "description": "The request attempted an operation that requires the ID of a customer, but the customer was not found. The request was rejected. Corrective action: Use the correct ID of the customer, a string starting with 'cus_'." }, { "name": "ERROR_GET_PAYMENT_METHOD", "description": "The request attempted an operation that requires the ID of a payment method, but the payment method was not found for the customer. The request was rejected. Corrective action: Add a valid payment method to the customer." }, { "name": "INVALID_CUSTOMER", "description": "The request attempted an operation that requires a valid customer ID, but the customer was not found. The request was rejected. Corrective action: Use the correct customer, or create a new customer." }, { "name": "INVALID_CUSTOMER_EMAIL", "description": "The request attempted an operation that requires a valid email address, but the information was not in proper email address format. The request was rejected. Corrective action: Use the correct format for an email address." }, { "name": "INVALID_CUSTOMER_FIRST_OR_LAST_NAME", "description": "The request attempted an operation that requires a customer, but the customer did not have a valid first name or last name. The request was rejected. Corrective action: Create a customer that has all fields required for this operation. Run 'Get Payment Method Required Fields'." }, { "name": "INVALID_CUSTOMER_ID", "description": "The request attempted an operation that requires a valid customer ID, but the customer was not found. The request was rejected. Corrective action: Use the correct customer, or create a new customer." }, { "name": "INVALID_CUSTOMER_NAME", "description": "The request tried to create a customer, but the name was missing. The request was rejected. Corrective action: In the 'name' field, provide the customer's full name." }, { "name": "INVALID_CUSTOMER_PHONE_NUMBER", "description": "The request tried to create a customer, but the phone number was not recognized. The request was rejected. Corrective action: Provide the customer's phone number in proper E.164 format." }, { "name": "INVALID_REQUIRED_PAYMENT_METHOD_FIELDS", "description": "The request tried to create or update a customer, or add or update a payment method for a customer, but a required field in the payment method was not found. The request was rejected. Corrective action: Use all fields required for the payment method." }, { "name": "INVALID_TOKENS_LIMIT", "description": "The request tried to retrieve a list of customers, but the value for the 'limit' query parameter was more than 30. The request was rejected. Corrective action: Set 'limit' from 1-30." } ] }, { "product": "disburse", "id": "service-provider-object", "type": "type", "name": "ServiceProvider", "description": "Service providers are companies that a consumer can pay using the payment mechanisms provided by a Rapyd partner.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "spp_" } ], "description": "ID of the service provider payment object, a string starting with **spp_**.", "required": true }, { "name": "amount", "description": "Amount of the payment, in units defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.", "type": [ { "type": "number" } ], "required": true }, { "name": "available_amounts", "type": [ { "type": "object" } ], "description": "Amounts available for recharge.", "required": true }, { "name": "brand", "type": [ { "type": "string" } ], "description": "Full name of the service provider.", "required": true }, { "name": "catalog_type", "type": [ { "type": "string" } ], "description": "Category of service provider. For example, \n**bills**, **education**, **financial_service**, **utility**", "required": true }, { "name": "catalog_sub_type", "type": [ { "type": "string" } ], "description": "Subcategory of service provider. For example, **electricity**, **water**, **gas**, **internet**", "required": true }, { "name": "catalog_subtype_options", "type": [ { "type": "array" } ], "description": "Optional fields for this service provider.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The country of the service provider. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the service provider payout, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "The currency accepted by the service provider. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the payment transaction.", "required": true }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the consumer's wallet. String starting with **ewallet_**.", "required": true }, { "name": "ewallets", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "One or more wallet objects containing these fields:\n\\* **ewallet_id** - ID of the consumer's wallet. String starting with **ewallet_**.\n\\* **amount** - Amount of the payment with this wallet, in units defined in `currency`. Decimal.\n\\* **percent** - Percentage of amount due, paid with this wallet.\n\\* **refunded_amount** - Amount refunded to this wallet.", "required": true }, { "name": "fields", "type": [ { "type": "object" } ], "description": "Object containing the fields required for the service provider. To get a list of required fields, use [Retrieve Service Provider Details](ref:retrieve-service-provider-details).\n\n**Note:** The 'fields' object can contain only fields that are either required or optional. A field with an unknown name will throw an error.", "required": true }, { "name": "hours_to_fulfill", "type": [ { "type": "number" } ], "description": "Maximum number of hours for a payment to appear on the consumer's bill. Integer from 0 to 72.", "required": true }, { "name": "icon_url", "type": [ { "type": "string" } ], "description": "URL for the icon image for the service provider.", "required": true }, { "name": "instructions", "type": [ { "type": "object" } ], "description": "Instructions for the consumer to make the payment.", "required": true }, { "name": "is_active", "type": [ { "type": "boolean" } ], "description": "Indicates whether this service provider is available.", "required": true }, { "name": "is_balance_check_supported", "type": [ { "type": "boolean" } ], "description": "Indicates whether this service provider supports checking a consumer's balance.", "required": true }, { "name": "is_cancelable", "type": [ { "type": "boolean" } ], "description": "Indicates whether this service provider supports canceling a payment.", "required": true }, { "name": "is_rechargeable", "type": [ { "type": "boolean" } ], "description": "Indicates whether this service provider supports recharging.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "paid_at", "type": [ { "type": "number" } ], "description": "Time that the service provider payout is closed, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "pay_options", "type": [ { "type": "object" } ], "description": "Reserved.", "required": true }, { "name": "reason", "type": [ { "type": "string" } ], "description": "Explanation for the `status`. Response only.", "required": true }, { "name": "recurrency_options", "type": [ { "type": "object" } ], "description": "Options for making recurrent payments.", "required": true }, { "name": "required_fields", "type": [ { "type": "object" } ], "description": "Contains the fields that this service provider requires for making a payment.", "required": true }, { "name": "service_provider", "type": [ { "type": "string" } ], "description": "The ID of the service provider.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "Exist", "NotExist" ] } ], "description": "Indicates whether a consumer has an account with a specified service provider. One of the following values:\n\\* **Exist**\n\\* **NotExist**\n\nResponse only.", "required": true }, { "name": "type", "type": [ { "type": "string" } ], "description": "The ID of the service provider.", "required": true } ] }, { "product": "disburse", "parent": "service-provider-object", "id": "list-service-providers", "type": "request", "name": "ListServiceProvidersRequest", "description": "Use the GET method to retrieve a list of all service providers.", "method": "GET", "path": "/v1/service_provider/catalog", "params": [], "body": [], "headers": [], "query": [ { "name": "catalog_sub_type", "type": [ { "type": "string" } ], "required": false, "description": "Subcategory of service provider. For example, **electricity**, **water**, **gas**, **internet**" }, { "name": "catalog_type", "type": [ { "type": "string" } ], "required": false, "description": "Category of service provider. For example, **bills**, **education**, **financial_service**, **utility**" }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "The country of the service provider. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "The currency accepted by the service provider. Three-letter ISO 4217 code. Uppercase." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of service providers to return. Range: 1-100. Default is 10." } ] }, { "product": "disburse", "parent": "service-provider-object", "id": "retrieve-service-provider-details", "type": "request", "name": "RetrieveServiceProviderDetailsRequest", "description": "Use the GET method to retrieve the details of a service provider, including required fields.", "method": "GET", "path": "/v1/service_provider/catalog/{service_provider}", "params": [ { "name": "service_provider", "type": [ { "type": "string" } ], "required": true, "description": "The name of the service provider." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "service-provider-object", "id": "validate-service-provider-account", "type": "request", "name": "ValidateServiceProviderAccountRequest", "description": "Use the POST method to determine whether a customer has an account with a service provider.", "method": "POST", "path": "/v1/service_provider/catalog/validate", "params": [], "body": [ { "name": "fields", "type": [ { "type": "string" } ], "required": true, "description": "Object containing the fields required for the service provider." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "ID of the service provider." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "service-provider-object", "id": "pay-service-provider", "type": "request", "name": "PayServiceProviderRequest", "description": "Use the POST method to transfer a payment from a consumer to a service provider.\n\nThis method triggers the **Service Provider Payment Created** webhook. This webhook contains the same information as the response.\n\nThe following asynchronous webhook provides information about later changes to the Service Provider object:\n* [Webhook - Service Provider Payment Completed](ref:webhook-service-provider-payment-completed)", "method": "POST", "path": "/v1/service_provider/catalog/pay", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "Amount of the payment, in units defined in `currency`." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "The currency accepted by the service provider. Three-letter ISO 4217 code. Uppercase." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the payment transaction." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the customer's wallet. String starting with **ewallet_**." }, { "name": "fields", "type": [ { "type": "string" } ], "required": true, "description": "Object containing the fields required for the service provider. To get a list of required fields, use [Retrieve Service Provider Details](ref:retrieve-service-provider-details)." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "ID of the service provider." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "service-provider-object", "id": "check-consumer-account-balance", "type": "request", "name": "CheckConsumerAccountBalanceRequest", "description": "Use the POST method to check a consumer's account balance with a service provider.", "method": "POST", "path": "/v1/service_provider/catalog/balance", "params": [], "body": [ { "name": "fields", "type": [ { "type": "string" } ], "required": true, "description": "Object containing the fields required for the service provider." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "ID of the service provider." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "service-provider-object", "id": "service-provider-errors", "type": "enum", "name": "ServiceProviderError", "values": [ { "name": "ERROR_MISSING_SERVICE_PROVIDER_CATALOG_TYPE", "description": "The request attempted an operation that requires a service provider type, but the 'type' field was empty or absent. The request was rejected. Corrective action: Use a value from the response to 'List Service Providers'." }, { "name": "ERROR_PAY_CATALOG_CURRENCY_NOT_SUPPORTED", "description": "The request tried to pay a service provider, but the currency in the request is not supported by the service provider. The request was rejected. Corrective action: Contact Client Support." }, { "name": "ERROR_SERVICE_PROVIDER_VALIDATION", "description": "The request tried to validate a service provider account, but the account was not recognized. The request was rejected. Corrective action: Provide all fields listed in the response to 'Retrieve Service Provider Details'." }, { "name": "INVALID_ACCOUNT_ID", "description": "The request attempted an operation that requires a service provider account number, but the account number was absent or not recognized. The request was rejected. Corrective action: In the 'fields' object, use the actual account number for the customer in the 'account_number' field." }, { "name": "INVALID_CATALOG_TYPE", "description": "The request attempted an operation that requires a service provider type, but the service provider type was not recognized. The request was rejected. Corrective action: For the service provider type, use a value from the response to 'List Service Providers'." }, { "name": "UNKNOWN_CATALOG_ITEM_REQUIRED_FIELD", "description": "The request attempted an operation that requires a specific field, but the field was missing. The request was rejected. Corrective action: In the 'fields' object, provide the parameter that is named at the end of the response code." } ] }, { "product": "wallet", "id": "wallet-contact-object", "type": "type", "name": "WalletContact", "description": "The Contact object represents a personal or business contact for a Rapyd Wallet.", "fields": [ { "description": "ID of the Contact object. String starting with **cont_**.", "type": [ { "type": "string", "startsWith": "cont_" } ], "name": "id", "required": true }, { "name": "address", "type": [ { "type": "object" }, { "type": "string" } ], "description": "Address of this contact person. Required when the client issues a card to the contact.\n\nThis can be an Address object or the ID of an address object created with [Create Address](ref:create-address). For more information, see [Address Object](#address-object).", "required": true }, { "name": "business_details", "type": [ { "type": "object" } ], "description": "Describes additional information for business entities. See ***Business Details Object***, below.\n\nRequired when `type` is **company**.", "required": true }, { "name": "compliance_profile", "type": [ { "type": "number" } ], "description": "Indicates the degree to which this contact can use the wallet. One of the following:\n\\* **1** - All transactions are allowed.\n\\* **0** - The wallet is limited, and the contact must complete the identity verification process.\n\\* **-1** - The wallet is restricted and cannot be used for any transactions.\n\nResponse only.", "required": true }, { "name": "contact_type", "type": [ { "type": "string", "possibleValues": [ "personal", "business" ] } ], "description": "Type of contact. One of the following:\n\\* **personal** - An individual customer.\n\\* **business** - A business customer.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.\n\nTo determine the code for a country, see [List Countries](ref:list-countries).", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the Contact object, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "date_of_birth", "type": [ { "type": "string" } ], "description": "Date of birth of the individual. Format: **MM/DD/YYYY**", "required": true }, { "name": "email", "type": [ { "type": "string" } ], "description": "Email address of the contact.", "required": true }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the Rapyd Wallet that this contact is associated with. String starting with **ewallet_**.", "required": true }, { "name": "first_name", "type": [ { "type": "string" } ], "description": "First name of the personal contact or primary person associated with the business contact.", "required": true }, { "name": "gender", "type": [ { "type": "string", "possibleValues": [ "male", "female", "other", "not_applicable" ] } ], "description": "Gender of the personal contact or primary person associated with the business contact. One of the following values:\n\\* **male**\n\\* **female**\n\\* **other**\n\\* **not_applicable**", "required": true }, { "name": "house_type", "type": [ { "type": "string", "possibleValues": [ "lease", "live_with_family", "own", "owner", "month_to_month", "housing_project" ] } ], "description": "Description of the type of residency at the contact's residence. One of the following values:\n\\* **lease** - A long-term lease.\n\\* **live_with_family** - The contact lives with family.\n\\* **own** - The contact owns the residence.\n\\* **owner** - The contact is the owner of the residence.\n\\* **month_to_month** - An informal agreement, renewable each month.\n\\* **housing_project** - A room in a large residence facility, such as a residence hall or senior citizens' home.", "required": true }, { "name": "identification_number", "type": [ { "type": "string" } ], "description": "ID number as shown by the ID document.", "required": true }, { "name": "identification_type", "type": [ { "type": "string" } ], "description": "Type of the identification document associated with the contact. Must be uppercase.\n\nFor types that are valid in the country, use [List Official Identification Documents](ref:list-official-identification-documents).", "required": true }, { "name": "issued_card_data", "type": [ { "type": "object", "fields": [ { "name": "preferred_name", "type": [ { "type": "unknown" } ] }, { "name": "transaction_permissions", "type": [ { "type": "unknown" } ] }, { "name": "role_in_company", "type": [ { "type": "unknown" } ] } ] } ], "description": "Describes additional information on the business contact for a company wallet. \n\nContains the following fields:\n\\* `preferred_name` - The name of the contact person.\n\\* `transaction_permissions` - Indicates permissions for issuing transactions. Possible values: **allowed**, **not_allowed**.\n\\* `role_in_company` - The role of the named person. One of the following values: **owner** (sole proprietor or partner), **agent** (authorized agent or attorney in fact), **employee** (authorized employee).", "required": true }, { "name": "last_name", "type": [ { "type": "string" } ], "description": "Family name of the personal contact or primary person associated with the business contact. This field is required to issue a card to a personal contact.", "required": true }, { "name": "marital_status", "type": [ { "type": "string", "possibleValues": [ "married", "single", "divorced", "widowed", "cohabiting", "not_applicable" ] } ], "description": "Marital status of the personal contact or primary person associated with the business contact. One of the following values:\n\\* **married**\n\\* **single**\n\\* **divorced** \n\\* **widowed**\n\\* **cohabiting**\n\\* **not_applicable**", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "middle_name", "type": [ { "type": "string" } ], "description": "Middle name of the personal contact or primary person associated with the business contact.", "required": true }, { "name": "mothers_name", "type": [ { "type": "string" } ], "description": "Name of the mother of the personal contact or primary person associated with the business contact. Alphabetic characters and spaces.", "required": true }, { "name": "nationality", "type": [ { "type": "string" } ], "description": "The citizenship of the contact. Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.\n\nTo determine the code for a country, see [List Countries](ref:list-countries).", "required": true }, { "name": "phone_number", "type": [ { "type": "string" } ], "description": "Phone number of the contact in E.164 format.", "required": true }, { "name": "second_last_name", "type": [ { "type": "string" } ], "description": "Second last name of the personal contact or primary person associated with the business contact.", "required": true }, { "name": "send_notifications", "type": [ { "type": "boolean" } ], "description": "Determines whether Rapyd sends notifications to the contact. Default is **false**.", "required": true }, { "name": "verification_status", "type": [ { "type": "string", "possibleValues": [ "not verified", "KYCd" ] } ], "description": "Result of the verification check. One of the following:\n\\* **not verified** - The contact has not been submitted for the Know Your Customer checks.\n\\* **KYCd** - The user has passed the Know Your Customer checks.", "required": true } ] }, { "product": "wallet", "parent": "wallet-contact-object", "id": "add-contact-to-wallet", "type": "request", "name": "AddContactToWalletRequest", "description": "Use the POST method to add a personal contact to a company wallet or client wallet.", "method": "POST", "path": "/v1/ewallets/{wallet}/contacts", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet that this contact is associated with. String starting with **ewallet_**." } ], "body": [ { "name": "address", "type": [ { "type": "object" } ], "required": false, "description": "Address object or address ID, a string starting with **address_**.." }, { "name": "contact_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of contact: **personal**." }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "2-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "date_of_birth", "type": [ { "type": "string" } ], "required": false, "description": "Date of birth of the individual. Format: MM/DD/YYYY" }, { "name": "email", "type": [ { "type": "string" } ], "required": false, "description": "Email address for the contact." }, { "name": "first_name", "type": [ { "type": "string" } ], "required": false, "description": "First name of the contact." }, { "name": "gender", "type": [ { "type": "string" } ], "required": false, "description": "Gender of the contact. One of the following values: **male**, **female**, **other**, **not_applicable**" }, { "name": "house_type", "type": [ { "type": "string" } ], "required": false, "description": "Description of the type of residency. One of the following values: **lease**, **live_with_family**, **own**, **owner**, **month_to_month**, **housing_project**" }, { "name": "identification_number", "type": [ { "type": "string" } ], "required": false, "description": "ID number as shown by the ID document. Alphanumeric string." }, { "name": "identification_type", "type": [ { "type": "string" } ], "required": false, "description": "Type of the identification document. For valid types, use [List Official Identification Documents](ref:list-official-identification-documents)." }, { "name": "last_name", "type": [ { "type": "string" } ], "required": false, "description": "Family name of the contact." }, { "name": "marital_status", "type": [ { "type": "string" } ], "required": false, "description": "Marital status of the contact. One of the following values: **married**, **single**, **divorced**, **widowed**, **cohabiting**, **not_applicable**" }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "middle_name", "type": [ { "type": "string" } ], "required": false, "description": "Middle name of the personal contact or primary person associated with the business contact." }, { "name": "mothers_name", "type": [ { "type": "string" } ], "required": false, "description": "Name of the contact's mother." }, { "name": "nationality", "type": [ { "type": "string" } ], "required": false, "description": "The citizenship of the contact. Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number of the contact in E.164 format." }, { "name": "second_last_name", "type": [ { "type": "string" } ], "required": false, "description": "Second last name of the contact." }, { "name": "send_notifications", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether Rapyd sends notifications to the contact. Default is **false**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-contact-object", "id": "update-wallet-contact", "type": "request", "name": "UpdateWalletContactRequest", "description": "Use the POST method to update a contact for a Rapyd Wallet.", "method": "POST", "path": "/v1/ewallets/{wallet}/contacts/{contact}", "params": [ { "name": "contact", "type": [ { "type": "string", "startsWith": "cont_" } ], "required": true, "description": "ID of the contact. String starting with **cont_**." }, { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet associated with the contact. String starting with **ewallet_**." } ], "body": [ { "name": "address", "type": [ { "type": "object" } ], "required": false, "description": "Address of the contact person. 'address' object. `name` and `line1` are required. **Note:** Do not use an address ID." }, { "name": "business_details", "type": [ { "type": "object" } ], "required": false, "description": "Defines additional descriptive details about business entities." }, { "name": "country", "type": [ { "type": "string" } ], "required": false, "description": "Country of the individual associated with the contact. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "date_of_birth", "type": [ { "type": "string" } ], "required": false, "description": "Date of birth of the individual. Format: **MM/DD/YYYY**" }, { "name": "email", "type": [ { "type": "string" } ], "required": false, "description": "Email address of the contact." }, { "name": "first_name", "type": [ { "type": "string" } ], "required": false, "description": "First name of the individual associated with the contact." }, { "name": "gender", "type": [ { "type": "string" } ], "required": false, "description": "Gender of the personal contact or primary person associated with the business contact. One of the following values: **male**, **female**, **other**, **not_applicable**" }, { "name": "house_type", "type": [ { "type": "string" } ], "required": false, "description": "Description of the type of residency. One of the following values: **lease**, **live_with_family**, **own**, **owner**, **month_to_month**, **housing_project**" }, { "name": "identification_number", "type": [ { "type": "string" } ], "required": false, "description": "ID number as shown by the ID document. Alphanumeric string." }, { "name": "identification_type", "type": [ { "type": "string" } ], "required": false, "description": "Type of the identification document. For valid types, use [List Official Identification Documents](ref:list-official-identification-documents)." }, { "name": "last_name", "type": [ { "type": "string" } ], "required": false, "description": "Family name of the individual associated with the contact." }, { "name": "marital_status", "type": [ { "type": "string" } ], "required": false, "description": "Marital status of the personal contact or primary person associated with the business contact. One of the following values: **married**, **single**, **divorced**, **widowed**, **cohabiting**, **not_applicable**" }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "middle_name", "type": [ { "type": "string" } ], "required": false, "description": "Middle name of the personal contact or primary person associated with the business contact." }, { "name": "mothers_name", "type": [ { "type": "string" } ], "required": false, "description": "Name of the contact's mother." }, { "name": "nationality", "type": [ { "type": "string" } ], "required": false, "description": "The citizenship of the contact. Two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number of the contact, in E.164 format." }, { "name": "second_last_name", "type": [ { "type": "string" } ], "required": false, "description": "Second last name of the personal contact or primary person associated with the business contact." }, { "name": "send_notifications", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether Rapyd sends notifications to the contact. Default is **false**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-contact-object", "id": "retrieve-wallet-contact", "type": "request", "name": "RetrieveWalletContactRequest", "description": "Use the GET method to retrieve a contact for an existing Rapyd Wallet.", "method": "GET", "path": "/v1/ewallets/{wallet}/contacts/{contact}", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet that this contact is associated with. String starting with **ewallet_**." }, { "name": "contact", "type": [ { "type": "string" } ], "required": true, "description": "ID of the contact. String starting with the prefix **cont_**." } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-contact-object", "id": "list-contacts-for-a-rapyd-wallet", "type": "request", "name": "ListContactsForARapydWalletRequest", "description": "Use the GET method to retrieve all contacts for a wallet.", "method": "GET", "path": "/v1/ewallets/{wallet}/contacts", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet that this contact is associated with. String starting with **ewallet_**." } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-contact-object", "id": "delete-wallet-contact", "type": "request", "name": "DeleteWalletContactRequest", "description": "Use the DELETE method to delete a personal contact from a company wallet or client wallet.", "method": "DELETE", "path": "/v1/ewallets/{wallet}/contacts/{contact}", "params": [ { "name": "contact", "type": [ { "type": "string" } ], "required": true, "description": "ID of the contact. String starting with the prefix **cont_**." }, { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet that this contact is associated with. String starting with **ewallet_**." } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-contact-object", "id": "wallet-contact-errors", "type": "enum", "name": "WalletContactError", "values": [ { "name": "BUSINESS_DETAILS_NOT_ALLOWED_FOR_PERSONAL_CONTACT", "description": "The request tried to create a personal contact for a Rapyd wallet, but the contact type was 'personal' and business details were given. Business details are not allowed for a personal contact. The request was rejected. Corrective action: In the 'contact' object, set 'business_details' to null." }, { "name": "CANNOT_CREATE_MORE_THAN_ONE_BUSINESS_CONTACT", "description": "The request tried to add a second business contact to a company wallet, but a company wallet can have only one business contact. The request was rejected. Corrective action: Set ‘contact_type' to 'personal’." }, { "name": "CREATE_PERSONAL_WALLET_REQUIRES_PERSONAL_CONTACT", "description": "The request tried to create a personal wallet, but the contact type was 'business'. The request was rejected. Corrective action: In the 'contact' object, set 'contact_type' to 'personal'." }, { "name": "ERROR_ADD_CONTACT_TOO_MANY_CONTACTS", "description": "The request tried to add a contact to a personal wallet, but a personal wallet can have only one contact. The request was rejected. Corrective action: None. Determine why an attempt was made to give a personal wallet two contacts. Consider creating a company wallet." }, { "name": "ERROR_CREATE_EWALLET_CONTACT", "description": "The request tried to create a contact in a wallet, but the operation failed. Corrective action: Verify that the wallet exists, and check all input parameters." }, { "name": "ERROR_DELETE_BUSINESS_CONTACT", "description": "The request tried to remove a business contact from a company wallet, but this operation is not possible. The request was rejected. Corrective action: None. If you are trying to replace the business contact with another business contact, use 'Update Wallet Contact'." }, { "name": "ERROR_DELETE_CONTACT_FROM_PERSONAL_EWALLET", "description": "The request tried to delete a contact, but the wallet was a personal wallet. A personal wallet can have only one contact and it cannot be deleted. The request was rejected. Corrective action: None. Determine why an attempt was made to delete the contact." }, { "name": "ERROR_DELETE_EWALLET_CONTACT", "description": "The request tried to delete a contact from a wallet, but the contact was not found. The request was rejected. Corrective action: Determine whether the contact was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_EWALLET_CONTACT_ADDRESS_CITY_NOT_FOUND", "description": "The request attempted an operation that requires a wallet contact, but the city of the contact was not found. The request was rejected. Corrective action: Use 'Update Wallet Contact' to add the name of the city to the 'city' field in the 'address' object." }, { "name": "ERROR_EWALLET_CONTACT_NOT_FOUND", "description": "The request attempted an operation that requires a wallet contact, but the contact was not found. The request was rejected. Corrective action: Provide the ID of a valid wallet contact, which is a string starting with 'cont_'." }, { "name": "ERROR_GET_EWALLET_CONTACT", "description": "The request attempted an operation that requires a wallet contact, but the contact was not found. The request was rejected. Corrective action: In the path, specify the ID of a valid wallet, a string starting with 'ewallet_', and the ID of a valid contact belonging to that wallet, a string starting with 'cont_'." }, { "name": "ERROR_UPDATE_EWALLET_CONTACT", "description": "The request tried to update a business wallet contact, but there was a format error in the business details. The request was rejected. Corrective action: Provide all data in the correct format. See the API reference." }, { "name": "ERROR_UPDATE_WALLET_CONTACT_TYPE", "description": "The request tried to change the type of a wallet contact, but this operation is not allowed. The request was rejected. Corrective action: None. Create a new wallet with the type of contact you want." }, { "name": "ERROR_WALLET_CONTACT_NATIONALITY_CODE_NOT_VALID", "description": "The request tried to add or update a nationality, but it was not in the correct format. The request was rejected. Corrective action: In the 'country' field, enter the 2-letter ISO 3166-1 ALPHA-2 country code." }, { "name": "EWALLET_BUSINESS_DETAILS_ADDRESS_NAME_NOT_VALID", "description": "The request created a wallet, but the address of the contact did not have a name. The wallet was created and it is not valid without it. Corrective action: Contact Client Support." }, { "name": "EWALLET_BUSINESS_DETAILS_ADDRESS_LINE1_NOT_VALID", "description": "The request created a wallet, but the address of the contact did not have a 'line1’ field or was not an object. The wallet was created and it is not valid without it. Corrective action: Contact Client Support." }, { "name": "EWALLET_UPDATED_WITH_NO_BUSINESS_DETAILS_DUE_TO_INVALID_ADDRESS", "description": "The request tried to update a wallet, but the business address was missing required information or contained special characters. The request was rejected. Corrective action: Inside the 'address' object, which is inside the 'business_details' object, provide 'name' with alphanumerics and spaces and 'line_1' with a string." }, { "name": "INVALID_EWALLET_BUSINESS_ENTITY_TYPE", "description": "The request tried to create a company wallet, but the entity type was missing or not recognized. The request was rejected. Corrective action: In the 'business_details' object, set 'entity_type' to one of the following values: 'sole_prop', 'partnership', 'company', 'government', 'charity', 'NPO', 'association', 'trust'." }, { "name": "INVALID_EWALLET_BUSINESS_NAME", "description": "The request tried to create a company wallet, but the business name was missing or contained special characters. The request was rejected. Corrective action: In the 'business_details' object, set the 'name' field to a string made up of alphabetic characters and spaces." }, { "name": "INVALID_EWALLET_BUSINESS_REGISTRATION_NUMBER", "description": "The request tried to create a company wallet, but the business registration number was missing or contained special characters. The request was rejected. Corrective action: In the 'business_details' object, set the 'registration_number' field to a string made up of alphabetic characters and spaces." }, { "name": "INVALID_EWALLET_BUSINESS_SUB_CATEGORY", "description": "The request tried to create an eWallet with the 'type' body parameter set to 'company', but 'business_sub_category' contained special characters. The request was rejected. Corrective action: Provide a valid business subcategory." }, { "name": "INVALID_EWALLET_CONTACT_TYPE", "description": "The request tried to create or update an eWallet contact, but the 'contact_type' was not recognized. The request was rejected. Corrective action: Set 'contact_type' to one of the following values: 'personal', 'business'" }, { "name": "INVALID_EWALLET_INDUSTRY_CATEGORY", "description": "The request tried to create an eWallet with the 'type' body parameter set to 'company', but 'industry_category' was not set or contained special characters. The request was rejected. Corrective action: Provide a valid industry category." }, { "name": "INVALID_GENDER", "description": "The request tried to create a wallet contact, but the gender was not recognized. The request was rejected. Corrective action: Set 'gender' to one of the following values: 'male', 'female', 'other', 'not_applicable'" }, { "name": "INVALID_HOUSE_TYPE", "description": "The request tried to create a wallet contact, but the house type was not recognized. The request was rejected. Corrective action: Set 'house_type' to one of the following values: 'lease', 'live_with_family', 'own', 'owner', 'month_to_month', 'housing_project'" }, { "name": "INVALID_MARITAL_STATUS", "description": "The request tried to create a wallet contact, but the marital status was not recognized. The request was rejected. Corrective action: Set 'marital_status' to one of the following values: 'married', 'single', 'divorced', 'widowed', 'cohabiting', 'not_applicable'" }, { "name": "INVALID_MIDDLE_NAME", "description": "The request tried to create a wallet contact, but the middle name contained special characters. The request was rejected. Corrective action: Use only alphabetic characters and spaces for 'middle_name'." }, { "name": "INVALID_SECOND_LAST_NAME", "description": "The request tried to create a wallet contact, but the second last name contained special characters. The request was rejected. Corrective action: Use only alphabetic characters and spaces for 'second_last_name'." } ] }, { "product": "collect", "id": "plan-object-collect", "type": "type", "name": "Plan", "description": "The Plan object describes a pricing structure for a single product of type **service**. A product can have multiple plans, for example, one plan for regular customers, and a special promotional plan for new customers that sign up in December.", "fields": [ { "description": "Unique ID for this plan. English alphanumeric characters with no special characters except underscore. If the client does not define an ID, Rapyd generates a string starting with **plan_**.", "type": [ { "type": "string", "startsWith": "plan_" } ], "name": "id", "required": true }, { "name": "aggregate_usage", "type": [ { "type": "string", "possibleValues": [ "max", "sum", "last_during_period", "last_ever" ] } ], "description": "Determines which quantity is used to calculate the pricing. One of the following:\n\\* **max** - The maximum reported usage within the billing cycle.\n\\* **sum** - The sum of all usage during a billing cycle. This is the default.\n\\* **last_during_period** - The last usage reported within the billing cycle.\n\\* **last_ever** - The last usage ever reported, if the latest billing cycles contain no usage at all.\n\nRequired when `usage_type` is **metered**.\n\nRelevant when `billing_scheme` is set to **per_unit**.", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount to charge, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.\n\nFor a free service, use 0. Must be null when `tiers` is set.\n\nRelevant when `billing_scheme` is set to **per_unit**.", "required": true }, { "name": "billing_scheme", "type": [ { "type": "string", "possibleValues": [ "per_unit", "tiered" ] } ], "description": "Describes how to compute the price. One of the following:\n\\* **per_unit** - The amount specified in `amount` is charged for each unit. Also set these related fields: `amount`, `transform_usage`, `usage_type`, `aggregate_usage`.\nThis is the default.\n\n\\* **tiered** - The unit pricing is computed using a tiering strategy as defined with the `tiers` and `tiers_mode` fields.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time the 'plan' object was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in fields that represent monetary amounts. Uppercase.", "required": true }, { "name": "interval", "type": [ { "type": "string", "possibleValues": [ "day", "week", "month", "year" ] } ], "description": "Specifies the units used in defining the billing cycle. One of the following:\n\\* **day**\n\\* **week**\n\\* **month**\n\\* **year**\n\nMaximum interval is 1 year.", "required": true }, { "name": "interval_count", "type": [ { "type": "number" } ], "description": "Number of time intervals in the billing cycle. Integer. See `interval`.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "nickname", "type": [ { "type": "string" } ], "description": "Brief description of the plan.", "required": true }, { "name": "product", "type": [ { "type": "string" }, { "type": "object", "id": "product-object" } ], "description": "The ID of the product that this plan is for, and fields describing this product in the plan.\n\nFor more information, see [Product Object](ref:product-object).", "required": true }, { "name": "tiers", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "fields": [ { "name": "amount", "type": [ { "type": "unknown" } ] }, { "name": "up_to", "type": [ { "type": "unknown" } ] }, { "name": "flat_amount", "type": [ { "type": "unknown" } ] } ], "id": "pricing-plans" } ] } ], "description": "Defines a tiered pricing structure. Each tier object represents a pricing tier, and contains the following fields:\n\\* `amount` - The price for each item in this tier. Decimal number.\n\\* `up_to` - The upper volume limit for this tier. Valid values: **inf** (infinite) or an integer.\n\\* `flat_amount` - Additional price for the entire tier. Default is 0.\n\nRelevant when `billing_scheme` is set to **tiered**. For more information, see [Pricing Plans](ref:pricing-plans).", "required": true }, { "name": "tiers_mode", "type": [ { "type": "string", "possibleValues": [ "graduated", "volume" ] } ], "description": "Determines the mode for calculating the total tiered charge. One of the following values: \n\\* **graduated** - The total cost at each price tier is calculated separately, then all tier charges are added together.\n\\* **volume** - The total cost is calculated as the number of items times the applicable tier price.\n\nRelevant when `billing_scheme` is set to **tiered**. For more information, see [Pricing Plans](ref:pricing-plans).", "required": true }, { "name": "transform_usage", "type": [ { "type": "object", "fields": [ { "name": "divide_by", "type": [ { "type": "unknown" } ] }, { "name": "round", "type": [ { "type": "unknown" } ] } ] } ], "description": "Defines the transformation that is applied to the reported usage before the billed price is computed. The transformation divides the quantity by the divisor specified in `divide_by`, then rounds up or down according to the setting in `round`. Relevant when `billing_scheme` is set to **per_unit**. \n\nContains the following fields:\n\\* `divide_by` - Indicates the divisor in the transformation calculation. Integer. Default is 1.\n\\* `round` - Indicates whether the reported number of units should be rounded **up** or **down** to the next whole quantity specified in `divide_by`. String. Default is **up**.\n\nFor more information, see ***Transformation Pricing*** in [Pricing Plans](ref:pricing-plans).\n\nRelevant when `billing_scheme` is set to **per_unit**.", "required": true }, { "name": "trial_period_days", "type": [ { "type": "number" } ], "description": "Specifies the number of days before charges begin to accrue. Use this parameter to define a free trial period for a service.", "required": true }, { "name": "usage_type", "type": [ { "type": "string", "possibleValues": [ "metered", "licensed" ] } ], "description": "Determines whether the customer is billed when the service is not actually used. Relevant when `billing_scheme` is set to **per_unit**. One of the following: \n\\* **metered** - The customer is billed only for actual usage. You must also set `aggregate_usage`.\n\\* **licensed** - The customer is billed even if the service is not used. This is the default.\n\nFor more information, see ***Transformation Pricing*** in [Pricing Plans](ref:pricing-plans).", "required": true } ] }, { "product": "collect", "parent": "plan-object-collect", "id": "create-plan", "type": "request", "name": "CreatePlanRequest", "description": "Use the POST method to create a pricing plan for services. Relevant to a product that has `type` set to **service**.\n\nThis method triggers the **Plan Created** webhook.", "method": "POST", "path": "/v1/plans", "params": [], "body": [ { "name": "aggregate_usage", "type": [ { "type": "string" } ], "required": false, "description": "Determines which quantity is used to calculate the pricing. Relevant when `usage_type` is **metered**. Default is *sum*." }, { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount to charge in the billing cycle. Use 0 for a free service. Must be null when `tiers` is set. Default is 0." }, { "name": "billing_scheme", "type": [ { "type": "string" } ], "required": false, "description": "Describes how to compute the price per billing period. One of the following values: **per_unit**, **tiered**" }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in fields that represent monetary amounts. Uppercase." }, { "name": "id", "type": [ { "type": "string", "startsWith": "plan_" } ], "required": false, "description": "Unique ID for this payment plan. English alphanumeric characters and underscore (_). Limited to 50 characters. If the merchant does not define an ID, Rapyd generates a string starting with **plan_**." }, { "name": "interval", "type": [ { "type": "string" } ], "required": true, "description": "Specifies the units used in defining the billing cycle." }, { "name": "interval_count", "type": [ { "type": "number" } ], "required": false, "description": "Number of intervals in the billing cycle. Default is **1**." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "nickname", "type": [ { "type": "string" } ], "required": false, "description": "Brief description of the pricing plan." }, { "name": "trial_period_days", "type": [ { "type": "number" } ], "required": false, "description": "Specifies the number of days before charges begin to accrue. Use this parameter to define a free trial period for a service." }, { "name": "product", "type": [ { "type": "string" } ], "required": true, "description": "Fields or ID of the 'product' object that this plan is for. The product must have `type` set to **service**." }, { "name": "tiers", "type": [ { "type": "string" } ], "required": false, "description": "Defines a tiered pricing structure. Array of objects. Must be null when `amount` is set." }, { "name": "tiers_mode", "type": [ { "type": "string" } ], "required": false, "description": "Determines the mode for calculating the total tiered charge." }, { "name": "transform_usage", "type": [ { "type": "string" } ], "required": false, "description": "Defines the transformation that is applied to the reported usage before the billed price is computed. Object." }, { "name": "usage_type", "type": [ { "type": "string" } ], "required": false, "description": "Determines whether the customer is billed when the service is not actually used. One of the following values: **metered**, **licensed**" } ], "headers": [], "query": [] }, { "product": "collect", "parent": "plan-object-collect", "id": "update-plan", "type": "request", "name": "UpdatePlanRequest", "description": "Use the POST method to change or modify a pricing plan for services. By design, you cannot change `amount`, `currency`, `interval` or `interval_count`.\n\nThis method triggers the **Plan Updated** webhook.", "method": "POST", "path": "/v1/plans/{plan}", "params": [ { "name": "plan", "type": [ { "type": "string" } ], "required": true, "description": "ID of the plan." } ], "body": [ { "name": "nickname", "type": [ { "type": "string" } ], "required": false, "description": "Brief description of the plan." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "plan-object-collect", "id": "retrieve-plan", "type": "request", "name": "RetrievePlanRequest", "description": "Use the GET method to retrieve the details of a pricing plan for services.", "method": "GET", "path": "/v1/plans/{plan}", "params": [ { "name": "plan", "type": [ { "type": "string" } ], "required": true, "description": "ID of the plan." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "plan-object-collect", "id": "list-plans", "type": "request", "name": "ListPlansRequest", "description": "Use the GET method to retrieve a list of all plans. Use the optional query parameters to filter the results. You can filter the results further by specifying one or more Plan fields as additional query parameters.", "method": "GET", "path": "/v1/plans", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the plan created after the last plan you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of plans to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the plan created before the first plan you want to retrieve." } ] }, { "product": "collect", "parent": "plan-object-collect", "id": "delete-plan", "type": "request", "name": "DeletePlanRequest", "description": "Use the DELETE method to delete a pricing plan for services.\n\nThis method triggers the **Plan Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/plans/{plan}", "params": [ { "name": "plan", "type": [ { "type": "string" } ], "required": true, "description": "ID of the plan." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "plan-object-collect", "id": "plan-errors", "type": "enum", "name": "PlanError", "values": [ { "name": "BILLING_SCHEME_SHOULD_BE_TIERED", "description": "The request tried to create a plan, but the request contains tiers and the 'billing_scheme' body parameter is not set to 'tiered'. The request was rejected. Corrective action: Set 'billing_scheme' to 'tiered' or remove the tiers." }, { "name": "ERROR_CREATE_PLAN", "description": "The request tried to create a plan, but the 'type' field of a product is set to 'goods'. The request was rejected. Corrective action: Add only products that have 'type' set to 'service'." }, { "name": "ERROR_CREATE_PLAN_INVALID_PRODUCT_TYPE", "description": "The request tried to create a plan, but the 'type' field of a product is set to 'goods'. The request was rejected. Corrective action: Add only products that have 'type' set to 'services'." }, { "name": "ERROR_CREATE_PLAN_MISSING_TIERS_OBJECT", "description": "The request tried to create a plan with 'billing_scheme' set to 'tiered', but the request does not define any tiers. The request was rejected. Corrective action: Set the 'tiers' object to contain one or more tiers." }, { "name": "ERROR_CREATE_PLAN_MISSING_TOP_TIER", "description": "The request tried to create a plan with 'billing_scheme' set to 'tiered', but the top tier was not defined. The request was rejected. Corrective action: Inside the 'tiers' object, for the top tier, set 'up_to' to 'inf'." }, { "name": "ERROR_CREATE_PLAN_PRODUCT_NOT_ACTIVE", "description": "The request tried to create a plan using a product that is not available for purchase. The request was rejected. Corrective action: Use 'Update Product' to set 'active' to true." }, { "name": "ERROR_CREATE_PLAN_TIER_PARAMETERS_NOT_VALID", "description": "The request tried to create a plan with 'billing_scheme' set to 'tiered', but the value for one of the fields in a tier object was not valid. The request was rejected. Corrective action: Set 'amount' and 'flat_amount' to a positive decimal number, and set 'up_to' to 'inf' or a positive integer." }, { "name": "ERROR_DELETE_PLAN", "description": "The request tried to delete a plan, but the operation failed. Corrective action: Determine whether the plan was already deleted, and why there were multiple requests to delete it." }, { "name": "ERROR_GET_PLAN", "description": "The request tried to retrieve a plan, but the plan was not found. The request was rejected. Corrective action: Use a valid plan ID." }, { "name": "ERROR_PLAN_CURRENCY_CODE_DOES_NOT_MATCH", "description": "The request tried to create a plan, but the currency of the subscription did not match the currency of all subscription items. The request was rejected. Corrective action: Add only plans that have the same currency as the subscription." }, { "name": "ERROR_PLAN_INTERVAL_COUNT_NOT_VALID", "description": "The request tried to create or update a plan, but the interval was defined for more than one year. The request was rejected. Corrective action: Provide correct values for 'interval' and 'interval_count' so that the defined interval is one year or less." }, { "name": "ERROR_PLAN_TRIAL_PERIOD_DAYS_DOES_NOT_MATCH", "description": "The request tried to create a plan, but the 'trial_period_days' field for the subscription did not match the 'trial_period_days' of all subscription items. The request was rejected. Corrective action: Add only plans that have the same 'trial_period_days' as the subscription, or change 'trial_period_days' in the relevant plans to match the value in the subscription." }, { "name": "ERROR_UPDATE_PLAN_INVALID_PRODUCT_TYPE", "description": "The request tried to update a plan, but the 'type' field of a product is set to 'goods'. The request was rejected. Corrective action: Add only products that have 'type' set to 'service'." }, { "name": "INVALID_AGGREGATE_USAGE", "description": "The request tried to create a plan, but the value of the 'aggregate_usage' body parameter was not recognized. The request was rejected. Corrective action: Set 'aggregate_usage' to one of the following values: 'max', 'sum', 'last_during_period', or 'last_ever'." }, { "name": "INVALID_AMOUNT_AND_TIERS", "description": "The request tried to create a plan, but the 'amount' and 'tiers' body parameters were both set. The request was rejected. Corrective action: Set 'amount' or 'tiers', but not both." }, { "name": "INVALID_BILLING_SCHEME", "description": "The request tried to create a plan, but the value of the 'billing_scheme' body parameter was unset or not recognized. The request was rejected. Corrective action: Set 'billing_scheme' to 'per_unit' or 'tiered'." }, { "name": "INVALID_PLAN_AND_PRODUCT", "description": "The request attempted an operation that requires a plan, but the plan was not found. The request was rejected. Corrective action: Use the ID of a valid plan." }, { "name": "INVALID_PLAN_ID", "description": "The request tried to retrieve a plan, but the plan was not found. The request was rejected. Corrective action: Use a valid plan ID." }, { "name": "INVALID_PLAN_INTERVAL", "description": "The request tried to create a plan or a subscription item. In the case of a plan, the 'interval' body parameter was not one of the following values: 'day', 'week', 'month', 'year'. In the case of a subscription item, the interval in the subscription item must be the same as the interval in the subscription. The request was rejected. Corrective action: Choose a correct value for 'interval', and make sure the intervals in the subscription and the subscription item are the same." }, { "name": "INVALID_TIERS", "description": "The request tried to create a plan, but one of the 'tier' objects failed to define 'amount' and 'up_to'. The request was rejected. Corrective action: Define the 'amount' and 'up_to' fields for each 'tier' object." }, { "name": "INVALID_TIERS_MODE", "description": "The request tried to create a plan, but the value for the 'tiers_mode' body parameter was not recognized. The request was rejected. Corrective action: Set 'tiers_mode' to one of the following values: 'graduated', 'volume'." }, { "name": "INVALID_TRANSFORM_USAGE", "description": "The request tried to create a plan, but the values for the fields of the 'transform_usage' object were not found or not recognized. The request was rejected. Corrective action: Set 'divide_by' to an integer and 'round' to 'up' or 'down'." }, { "name": "INVALID_TRIAL_PERIOD_DAYS", "description": "The request tried to create or update a plan, but the value of the 'trial_period_days' body parameter was not recognized. The request was rejected. Corrective action: Set 'trial_period_days' to a positive integer. If there is no free trial, do not set this parameter." }, { "name": "INVALID_USAGE_TYPE", "description": "The request tried to create a plan, but the value of the 'usage_type' body parameter was not recognized. The request was rejected. Corrective action: Set 'usage_type' to one of the following values: 'metered', 'licensed'." } ] }, { "product": "disburse", "id": "subscription-object-disburse", "type": "type", "name": "Subscription", "description": "A subscription object defines a recurring payout. Before you create a subscription, you must create a product and a plan.\n\nNote the following when creating a subscription for recurring payouts:\n> \\* Only one subscription item is supported and it cannot be deleted. You cannot create an additional subscription item.\n> \\* `amount` is only indicated in the plan that is referenced in the subscription item. The `usage_type` in the plan must be **licensed**.\n> \\* The `type` of the product in the plan must be **service**.\n> \\* The subscription can only be canceled at the end of a cycle.\n> \\* Coupons, trial periods, and taxes are not supported.", "fields": [ { "description": "ID of the Subscription object. String starting with **sub_**.", "type": [ { "type": "string", "startsWith": "sub_" } ], "name": "id", "required": true }, { "name": "billing", "type": [ { "type": "string" } ], "description": "Determines the method of operation at the end of the payout cycle. Set to **pay_automatically** - Rapyd generates a 'payout' object, then attempts to pay it using the designated payout method.", "required": true }, { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "description": "Determines the last date that the payout is transferred. \n\n\\* **false** - When the subscription is created, no end is defined.\n\\* **true** - Payout is transferred until the end of the current cycle, then the subscription is canceled. The value must be **true** when canceling a payout subscription.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "payout_fields", "type": [ { "type": "object", "id": "payout-object" } ], "description": "Contains fields of the 'payout' object. Defines a recurring payout, such as disbursement of pensions or salaries. For more information, see [Payout Object](ref:payout-object) .", "required": true }, { "name": "subscription_items", "type": [ { "type": "object", "fields": [ { "name": "plan", "type": [ { "type": "unknown" } ] }, { "name": "quantity", "type": [ { "type": "unknown" } ] }, { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ] } ], "description": "In payout subscription requests, an object containing the following fields:\n\\* `plan` - ID of a plan that describes the service and pricing structure. String.\n\\* `quantity` - Number of units of the service described in `plan`.\n\nIn responses, an object containing the following fields:\n\\* `data` - One subscription item.\n\\* `has_more` - Indicates whether there are more than three items in this subscription. In payout subscription, the value is always **false**.\n\\* `total_count` - Total number of items in this subscription. In payout subscription, the value is always **1**.\n\\* `url` - URL for requesting all of the items in this subscription.", "required": true }, { "description": "Total amount of subscription items that are not displayed.", "type": [ { "type": "number" } ], "name": "total_count", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "payment", "payout" ] } ], "description": "The type of the subscription. One of the following values:\n\\* **payment**\n\\* **payout**", "required": true } ] }, { "product": "disburse", "parent": "subscription-object-disburse", "id": "create-subscription-disburse", "type": "request", "name": "CreateSubscriptionRequest", "description": "Use the POST method to create a payout subscription.\n\n**Additional information**\n\n \\* To force the subscription to terminate at the end of the first cycle defined in the plan, set `cancel_at_period_end` to **true**.\n\nFor more information about defining the subscription cycle, see [Plan Object - Disburse](ref:plan-object-disburse).\n\nThis method triggers the **Customer Payout Subscription Created** webhook. This webhook contains the same information as the response.\n\n**Note:** Only clients with [PCI](ref:glossary) certification can handle personal identifying information for cards. Clients that are not PCI-certified can use [Rapyd Checkout](doc:rapyd-checkout-overview) to collect money from a card.", "method": "POST", "path": "/v1/payouts/subscriptions/", "params": [], "body": [ { "name": "billing", "type": [ { "type": "string" } ], "required": true, "description": "Determines the method of billing. For payout subscription, set to **pay_automatically**." }, { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "required": false, "description": "Terminates the subscription at the end of the current billing period. Default is **false**." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payout_fields", "type": [ { "type": "string" } ], "required": false, "description": "Object containing fields of the Payout object. `amount` is taken from the plan. See also [Payout Object](ref:payout-object)." }, { "name": "subscription_items", "type": [ { "type": "string" } ], "required": false, "description": "An array containing one object that describes a subscription item. For details, see [Subscription Object - Disburse](ref:subscription-object-disburse)." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "subscription-object-disburse", "id": "update-subscription-disburse", "type": "request", "name": "UpdateSubscriptionRequest", "description": "Use the POST method to change or modify a payout subscription.", "method": "POST", "path": "/v1/payouts/subscriptions/{subscription}", "params": [ { "name": "subscription", "type": [ { "type": "object" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [ { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "subscription-object-disburse", "id": "retrieve-subscription-disburse", "type": "request", "name": "RetrieveSubscriptionRequest", "description": "Use the GET method to retrieve the details of a subscription.", "method": "GET", "path": "/v1/payouts/subscriptions/{subscription}", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "subscription-object-disburse", "id": "list-subscriptions-disburse", "type": "request", "name": "ListSubscriptionsRequest", "description": "Use the GET method to retrieve a list of subscriptions. You can filter the list with one or more query parameters.", "method": "GET", "path": "/v1/payouts/subscriptions", "params": [], "body": [], "headers": [], "query": [ { "name": "billing", "type": [ { "type": "string" } ], "required": false, "description": "Method of billing. Set to **pay_automatically**." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "ID of the customer. String starting with **cus_**." }, { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a record in the list. The list ends with the last record that was created before the record with this ID. Use this filter to get the previous page of results." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of subscriptions to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of a record in the list. The list begins with the record that was created next after the record with this ID. Use this filter to get the next page of results. Relevant when `ending_before` is not used." }, { "name": "status", "type": [ { "type": "string" } ], "required": false, "description": "Status of the subscription. One of the following: **active**, **canceled**, **trialing**" } ] }, { "product": "disburse", "parent": "subscription-object-disburse", "id": "cancel-subscription-disburse", "type": "request", "name": "CancelSubscriptionRequest", "description": "Use the DELETE method to cancel a subscription at the end of the current cycle. \n\nThis method triggers the **Customer Payout Subscription Canceled** webhook. This webhook contains the same information as the response.\n\n\nFor more information about defining the subscription cycle, see [Plan Object - Disburse](ref:plan-object-disburse).", "method": "DELETE", "path": "/v1/payouts/subscriptions/{subscription}", "params": [ { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": true, "description": "ID of the subscription. String starting with **sub_**." } ], "body": [ { "name": "cancel_at_period_end", "type": [ { "type": "boolean" } ], "required": false, "description": "Cancels the subscription at the end of the current period. Set to **true**." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "subscription-object-disburse", "id": "payout-subscription-errors", "type": "enum", "name": "PayoutSubscriptionError", "values": [ { "name": "ERROR_CREATE_SUBSCRIPTION", "description": "The request tried to create a payout subscription, but the method of payout was not found. The request was rejected. Corrective action: In the 'payout_fields' object, include all fields that are required by the payout method type, as indicated in the response to 'Get Payout Required Fields'." }, { "name": "ERROR_CREATE_SUBSCRIPTION_ITEM_PAYOUT_SUBSCRIPTION", "description": "The request tried to add a subscription item to a payout subscription, but the maximum number of subscription items in a payout subscription is 1. The request was rejected. Corrective action: None. Determine why an attempt was made to add a subscription item to a payout subscription." }, { "name": "ERROR_UPDATE_SUBSCRIPTION_PAYOUT_FIELDS", "description": "The request tried to update payout fields in a payout subscription, but both the 'description' and the 'metadata' fields were missing. The request was rejected. Corrective action: Provide a 'description' or 'metadata' field in the 'payout_fields' object." }, { "name": "INVALID_PAYOUT_SUBSCRIPTION_ITEM_QUANTITY", "description": "The request attempted a payout subscription operation, but the quantity was not valid. The request was rejected. Corrective action: Set subscription item 'quantity' to 1." }, { "name": "INVALID_PAYOUT_SUBSCRIPTION_PLAN_USAGE_TYPE", "description": "The request tried to create or update a payout subscription, but the usage type of the plan was not 'licensed'. The request was rejected. Corrective action: Use a plan with 'usage_type' set to 'licensed'." } ] }, { "product": "wallet", "id": "wallet-object", "type": "type", "name": "Wallet", "description": "", "fields": [ { "description": "Unique identifier of the wallet object. String starting with **ewallet_**.", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "name": "id", "required": true }, { "name": "accounts", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "fields": [ { "name": "id", "type": [ { "type": "unknown" } ] }, { "name": "alias", "type": [ { "type": "unknown" } ] }, { "name": "balance", "type": [ { "type": "unknown" } ] }, { "name": "currency", "type": [ { "type": "unknown" } ] }, { "name": "limit", "type": [ { "type": "unknown" } ] }, { "name": "limits", "type": [ { "type": "unknown" } ] }, { "name": "on_hold_balance", "type": [ { "type": "unknown" } ] }, { "name": "received_balance", "type": [ { "type": "unknown" } ] }, { "name": "reserve_balance", "type": [ { "type": "unknown" } ] } ] } ] } ], "description": "An array of objects with the following fields:\n\\* `id` - ID of the account. UUID.\n\\* `alias` - Three-letter ISO 4217 code for the currency of the account.\n\\* `balance` - Available funds in the account.\n\\* `currency` - Three-letter ISO 4217 code for the currency used in the `balance` field. Uppercase.\n\\* `limit` - Reserved.\n\\* `limits` - Reserved.\n\\* `on_hold_balance` - Amount in the on-hold balance of the account.\n\\* `received_balance` - Amount of escrow funds in the account.\n\\* `reserve_balance` - Amount in the reserve balance of the account.\n\nResponse only.", "required": true }, { "name": "category", "type": [ { "type": "string", "possibleValues": [ "collect", "disburse", "card_authorization", "general" ] } ], "description": "Indicates the type of client wallet. One of the following:\n\\* **collect**\n\\* **disburse**\n\\* **card_authorization**\n\\* **general**\nRelevant to client wallets. Read-only.", "required": true }, { "name": "contacts", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "wallet-contact-object" } ] } ], "description": "Describes details about the wallet contacts. See [Wallet Contact Object](ref:wallet-contact-object). A 'person' wallet can have only one contact.", "required": true }, { "name": "contacts", "type": [ { "type": "object", "fields": [ { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ], "id": "wallet-contact" } ], "description": "Contains the following fields:\n\n\\* `data` - An array of ‘contact’ objects. See [Wallet Contact](ref:wallet-contact).\n\n\\* `has_more` - Boolean. Indicates whether there are more contacts than appear in the ‘data’ array.\n\n\\* `total_count` - Number. The total number of contacts in the wallet.\n\n\\* `url` - String. URL to retrieve all contacts in the wallet. Use HTTP GET.\n\nResponse only.", "required": true }, { "name": "email", "type": [ { "type": "string" } ], "description": "Email address of the wallet owner.", "required": true }, { "name": "ewallet_reference_id", "type": [ { "type": "string" } ], "description": "Wallet ID defined by the customer or end user. Must be unique.", "required": true }, { "name": "first_name", "type": [ { "type": "string" } ], "description": "First name of the wallet owner.", "required": true }, { "name": "last_name", "type": [ { "type": "string" } ], "description": "Family name of the wallet owner.", "required": true }, { "description": "A JSON object defined by the client.", "type": [ { "type": "object" } ], "name": "metadata", "required": true }, { "name": "phone_number", "type": [ { "type": "string" } ], "description": "Phone number of the wallet owner in E.164 format.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "ACT", "DIS" ] } ], "description": "Status of the wallet. One of the following:\n\\* **ACT** - Active.\n\\* **DIS** - Disabled.\n\nResponse only.", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "company", "person", "client" ] } ], "description": "Type of wallet. One of the following:\n\\* **company** - Indicates a business wallet. \n\\* **person** - Indicates the wallet of an individual consumer. \n\\* **client** - Indicates a wallet for the Rapyd client. Contact Rapyd support to create this type of wallet.", "required": true }, { "name": "verification_status", "type": [ { "type": "string", "possibleValues": [ "not verified", "KYCd" ] } ], "description": "Result of the verification check. One of the following:\n\\* **not verified** - The contact has not been submitted for the Know Your Customer checks.\n\\* **KYCd** - The user has passed the Know Your Customer checks.\n\nResponse only.", "required": true } ] }, { "product": "wallet", "parent": "wallet-object", "id": "create-wallet", "type": "request", "name": "CreateWalletRequest", "description": "Use the POST method to create a Rapyd Wallet.\n\nThe following types of wallet are supported:\n \\* **Person** - Requires one personal contact.\n \\* **Company** - Requires one business contact. You can add personal contacts as required. See [Add Contact to Wallet](ref:add-contact-to-wallet).\n \\* **Client** - Requires one business contact. Created by **[Rapyd Client Support](https://support.rapyd.net)**.", "method": "POST", "path": "/v1/user", "params": [], "body": [ { "name": "contact", "type": [ { "type": "object", "id": "wallet-contact-object" } ], "required": true, "description": "Describes details about the wallet contacts. Array of objects. See [Wallet Contact Object](ref:wallet-contact-object)." }, { "name": "email", "type": [ { "type": "string" } ], "required": false, "description": "Email address of the wallet owner." }, { "name": "ewallet_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "Rapyd Wallet ID defined by the customer or end user. Must be unique." }, { "name": "first_name", "type": [ { "type": "string" } ], "required": false, "description": "First name of the Rapyd Wallet owner." }, { "name": "last_name", "type": [ { "type": "string" } ], "required": false, "description": "Family name of the Rapyd Wallet owner." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number of the wallet owner in E.164 format." }, { "name": "type", "type": [ { "type": "string" } ], "required": false, "description": "Type of wallet: **company** or **person**. Default is **person**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-object", "id": "update-wallet", "type": "request", "name": "UpdateWalletRequest", "description": "Use the PUT method to change or modify a Rapyd Wallet.", "method": "PUT", "path": "/v1/user", "params": [], "body": [ { "name": "email", "type": [ { "type": "string" } ], "required": false, "description": "Email address of the wallet owner." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**. Required when `phone number` is not used." }, { "name": "ewallet_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "Rapyd Wallet ID defined by the customer or end user. Must be unique." }, { "name": "first_name", "type": [ { "type": "string" } ], "required": false, "description": "First name of the Rapyd Wallet owner." }, { "name": "last_name", "type": [ { "type": "string" } ], "required": false, "description": "Family name of the Rapyd Wallet owner." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number of the wallet owner in E.164 format." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-object", "id": "disable-wallet", "type": "request", "name": "DisableWalletRequest", "description": "Use the PUT method to block the Rapyd Wallet. This action prevents the following actions:\n\nmovement of money into or out of the wallet, and also prevents issuing a bank account number or card to the wallet..\n\nUse this method when the customer requests it, or while you conduct an investigation. Undo the process with [Enable Wallet](ref:enable-wallet).\n\nThis method changes the status of the wallet to **DIS** (disabled) and triggers the **Wallet Disabled** webhook.", "method": "PUT", "path": "/v1/user/disable", "params": [], "body": [ { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**. Required when `phone number` is not used." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number of the Rapyd Wallet in E.164 format. Required when `ewallet` field is not used." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-object", "id": "enable-wallet", "type": "request", "name": "EnableWalletRequest", "description": "Use the PUT method to enable a Rapyd Wallet that was previously disabled with [Disable Wallet](ref:disable-wallet).\n\nThis method changes the status of the wallet to **ACT** (enabled and active) and triggers the **Wallet Enabled** webhook.", "method": "PUT", "path": "/v1/user/enable", "params": [], "body": [ { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**. Required when `phone number` is not used." }, { "name": "phone_number", "type": [ { "type": "string" } ], "required": false, "description": "Phone number of the Rapyd Wallet in E.164 format. Required when `ewallet` field is not used." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-object", "id": "retrieve-wallet", "type": "request", "name": "RetrieveWalletRequest", "description": "Use the GET method to retrieve the details of a Rapyd Wallet.", "method": "GET", "path": "/v1/user/{wallet}", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**" } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-object", "id": "delete-wallet", "type": "request", "name": "DeleteWalletRequest", "description": "Use the DELETE method to delete a Rapyd Wallet. Use this method when the wallet has never been used.\n\nThis method triggers the **Wallet Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/user/{wallet}", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet. String starting with **ewallet_**" } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-object", "id": "wallet-errors", "type": "enum", "name": "WalletError", "values": [ { "name": "ERROR_CREATE_USER_INVALID_EWALLET_REFERENCE_ID", "description": "The request tried to create a wallet, but the ewallet reference ID was not valid. The request was rejected. Corrective action: Set ‘ewallet_reference_id’ to a string of less than 200 characters." }, { "name": "ERROR_CREATE_USER_EWALLET_REFERENCE_ID_ALREADY_EXISTS", "description": "The request tried to create a wallet, but the reference ID was already in use. The request was rejected. Corrective action: For 'ewallet_reference_id', enter a unique string." }, { "name": "ERROR_EWALLET_DISABLED", "description": "The request attempted an operation that requires a wallet, but the wallet is disabled. The request was rejected. Corrective action: Enable the wallet." }, { "name": "ERROR_FIRST_NAME_CONTAINS_ILLEGAL_CHARS", "description": "The request attempted an operation that requires a person's first name, but the name contained special characters. The request was rejected. Corrective action: Use only alphabetic characters and spaces for 'first_name'." }, { "name": "ERROR_GET_EWALLET", "description": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet, a string starting with 'ewallet_'." }, { "name": "ERROR_GET_USER", "description": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use a valid wallet ID, which is a string starting with 'ewallet_'." }, { "name": "ERROR_INVALID_EWALLET", "description": "The request attempted an operation that requires a wallet, but the wallet was not recognized. The request was rejected. Corrective action: Use the ID of a valid wallet, a string starting with 'ewallet_'." }, { "name": "ERROR_INVALID_EWALLET_REFERENCE_ID", "description": "The request attempted an operation that requires the ewallet reference ID, but the ewallet ID was not valid. The request was rejected. Corrective action: Set 'ewallet_reference_id' to a string of less than 200 characters." }, { "name": "ERROR_INVALID_EWALLET_TYPE", "description": "The request attempted an operation that requires the 'type' parameter, but the 'type' was not a recognized value. The request was rejected. Corrective action: Set 'type' to one of the following values: 'person', 'company', 'client'." }, { "name": "ERROR_INVALID_EWALLET_VERIFICATION_STATUS", "description": "The request attempted an operation that requires the verification status, but the verification status was not valid. The request was rejected. Corrective action: Set 'verification_status' to one of the following values: 'verified', 'not verified'" }, { "name": "ERROR_PAYCODE_AND_REFUND_CODE_OBSOLETE", "description": "The request attempted an operation that requires a pay code or refund code, but these codes are now obsolete. The request was rejected. Corrective action: Use 'Create Payment' and related methods." }, { "name": "ERROR_UPDATE_EWALLET_TYPE", "description": "The request tried to update a wallet type, but the 'type' cannot be changed. The request was rejected. Corrective action: None. Create a new wallet." }, { "name": "ERROR_UPDATE_FUNDS", "description": "The request tried to add funds to or remove funds from a wallet, but the wallet was not found. The request was rejected. Corrective action: Use a valid wallet phone number in E.164 format, or a valid wallet ID, which is a string starting with 'ewallet_'." }, { "name": "ERROR_UPDATE_USER", "description": "The request tried to update a wallet, but the wallet was not found. The request was rejected. Corrective action: Use a valid wallet phone number in E.164 format, or a valid wallet ID, which is a string starting with 'ewallet_'." }, { "name": "ERROR_UPDATE_USER_EWALLET_REFERENCE_ID_ALREADY_EXISTS", "description": "The request tried to update a wallet, but the reference ID was already in use. The request was rejected. Corrective action: For 'ewallet_reference_id', enter a unique string." }, { "name": "EWALLET_BUSINESS_DETAILS_ADDRESS_LINE1_NOT_VALID", "description": "The request created a company wallet, but the first line of the business address was not found. The wallet was created with no 'business_details' object, and it is not valid without it. Corrective action: Use 'Update Wallet' to set 'line1' in the 'address' object to a string made up of alphabetic characters and spaces." }, { "name": "EWALLET_BUSINESS_DETAILS_ADDRESS_NAME_NOT_VALID", "description": "The request created a company wallet, but the name associated with the business address was not found or contained special characters. The wallet was created with no 'business_details' object, and it is not valid without it. Corrective action: Use 'Update Wallet' to set 'name' in the 'address' object to a string made up of alphabetic characters and spaces." }, { "name": "EWALLET_UPDATED_WITH_NO_BUSINESS_DETAILS_DUE_TO_INVALID_ADDRESS", "description": "The request tried to update a wallet, but the business address was missing required information or contained special characters. The request was rejected. Corrective action: Inside the 'address' object, which is inside the 'business_details' object, provide 'name' with alphanumerics and spaces and 'line_1' with a string." }, { "name": "EWALLET_WITH_ACCOUNT_CANNOT_BE_DELETED", "description": "The request tried to delete a wallet, but the wallet held an account. The request was rejected. Corrective action: None. Determine why an attempt was made to delete the wallet." }, { "name": "INVALID_EMAIL", "description": "The request attempted an operation that requires an email address, but the email was not valid or is already in use. The request was rejected. Corrective action: Provide a valid, unique email address for 'email'." }, { "name": "INVALID_EWALLET_TYPE", "description": "The request tried to create a wallet, but the 'type' body parameter was not a recognized value. The request was rejected. Corrective action: Set 'type' to one of the following values: 'person', 'company'." }, { "name": "INVALID_LAST_NAME", "description": "The request tried to perform an operation that requires the family name of an individual, but the 'last_name' field was blank or invalid. The request was rejected. Corrective action: Submit a valid last name." }, { "name": "MISSING_EWALLET_CONTACT_TYPE", "description": "The request tried to create or update a wallet contact, but the 'contact_type' was missing. The request was rejected. Corrective action: Set 'contact_type' to one of the following values: 'personal', 'business'" }, { "name": "MISSING_EWALLET_ID", "description": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet." }, { "name": "MISSING_EWALLET_TOKEN", "description": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Provide a valid wallet ID." }, { "name": "MISSING_PHONE_NUMBER_OR_EWALLET_ID", "description": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Provide the wallet's phone number in E.164 format or wallet ID, which is a string starting with 'ewallet_'." }, { "name": "USER_ALREADY_EXISTS", "description": "The request tried to assign a phone number to a wallet, but the phone number is already in the database. A wallet must have a unique phone number, but wallet contacts are not restricted. The request was rejected. Corrective action: In the 'contact' object, assign the number to the 'phone_number' field." } ] }, { "product": "collect", "id": "group-payment-object", "type": "type", "name": "GroupPayment", "description": "The Group Payment object describes a payment where the funds are collected from two to ten payment methods.", "fields": [ { "description": "ID of the Group Payment object. String starting with **gp_**.", "type": [ { "type": "string", "startsWith": "gp_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the group payment, in units defined by `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.", "required": true }, { "name": "amount_to_replace", "type": [ { "type": "string" } ], "description": "Indicates the total amount of failed payments that have not been replaced. Response only.", "required": true }, { "description": "Reason for cancellation of the group payment. Response only.", "type": [ { "type": "string" } ], "name": "cancel_reason", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "Country where the payment methods are supported. Two-letter ISO 3166-1 ALPHA-2 code. Response only.", "required": true }, { "name": "country_code", "type": [ { "type": "string" } ], "description": "Country where the payment methods are supported. Two-letter ISO 3166-1 ALPHA-2 code. Response only.", "required": true }, { "type": [ { "type": "string" } ], "name": "currency", "description": "Currency of the payments. Three-letter ISO 4217 code.", "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "Currency of the payments. Three-letter ISO 4217 code. Response only.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the group payment.", "required": true }, { "name": "expiration", "type": [ { "type": "number" } ], "description": "End of the time allowed for customers to make this payment, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "Merchant-defined ID. Limited to 255 characters.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "payments", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "payment-object" } ] } ], "description": "Array of Payment objects. All payments must have the same currency and must be supported in the same country.\n\nFor more information, see [Payment Object](ref:payment-object).", "required": true }, { "description": "Reason for cancellation of the group payment.", "name": "reason", "type": [ { "type": "string" } ], "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "active", "canceled", "closed" ] } ], "description": "Indicates the status of the group payment operation. One of the following values:\n* **active** - The group payment was created and one or more payments are still open.\n* **canceled** - The group payment was canceled.\n* **closed** - All payments in the group payment are complete.\n\nResponse only.", "required": true } ] }, { "product": "collect", "parent": "group-payment-object", "id": "create-group-payment", "type": "request", "name": "CreateGroupPaymentRequest", "description": "Use the POST method to create a Group Payment.\n\nEach payment in the group payment must be from a different payment method.\n\nThis method triggers the **Payment Succeeded** webhook. This webhook contains the same information as the response.\n\nIf all payments use a **card** payment method with `capture` set to **true**, the following additional webhooks are triggered:\n* **Payment Completed**\n* ** Group Payment Completed**\n\nThe following asynchronous webhooks provide information about later changes to the Group Payment object:\n* [Webhook - Payment Completed](ref:webhook-payment-completed) \n* [Webhook - Group Payment Completed](ref:webhook-group-payment-completed)\n\n> **Note:** Clients who have PCI clearance can use this method to collect money from a card.", "method": "POST", "path": "/v1/payments/group_payments", "params": [], "body": [ { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the group payment transaction." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "ID defined by the client.. Limited to 255 characters." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payments", "type": [ { "type": "string" } ], "required": true, "description": "Array of 'payment' objects." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "group-payment-object", "id": "retrieve-group-payment", "type": "request", "name": "RetrieveGroupPaymentRequest", "description": "Use the GET method to retrieve details of a group payment.", "method": "GET", "path": "/v1/payments/group_payments/{group_payment}", "params": [ { "name": "group_payment", "type": [ { "type": "string", "startsWith": "gp_" } ], "required": true, "description": "ID of the group payment. String starting with **gp_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "group-payment-object", "id": "cancel-group-payment", "type": "request", "name": "CancelGroupPaymentRequest", "description": "Use the DELETE method to cancel a group payment. All payments in the group payment must be cancelable, and they must all have 'status' = **ERR** or **ACT**. To determine whether a payment method is cancelable, use [List Payment Methods by Country](ref:list-payment-methods-by-country).", "method": "DELETE", "path": "/v1/payments/group_payments/{group_payment}", "params": [ { "name": "group_payment", "type": [ { "type": "string", "startsWith": "gp_" } ], "required": true, "description": "ID of the group payment. String starting with **gp_**." } ], "body": [ { "name": "reason", "type": [ { "type": "string" } ], "required": false, "description": "Reason for cancellation of the group payment." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "group-payment-object", "id": "create-group-refund", "type": "request", "name": "CreateGroupRefundRequest", "description": "Use the POST method to refund a group payment. The refund is credited against a specific group payment. The money is returned to the payment methods that were used for the payment. \n\n> **Note:** The `status` of the group payment must be **closed**.", "method": "POST", "path": "/v1/refunds/group_payments", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the refund, in the currency of the group payment. Decimal. If this parameter is omitted, the entire group payment is refunded." }, { "name": "group_payment", "type": [ { "type": "string", "startsWith": "gp_" } ], "required": true, "description": "ID of the group payment that the refund is charged against. String starting with **gp_**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "group-payment-object", "id": "group-payment-errors", "type": "enum", "name": "GroupPaymentError", "values": [ { "name": "ERROR_CARD_VALIDATION_IN_GROUP_PAYMENT", "description": "The request attempted to validate a card as part of a group payment. The request was rejected. Corrective action: Create a payment with a card payment method, set 'capture' to false, set 'amount’ to 0, and list only one payment in the 'payments' array." }, { "name": "ERROR_CASH_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "description": "The request tried to create a group payment, but one of the payment methods in the individual payments was a cash payment method. The request was rejected. Corrective action: For all payments, use the following types of payment methods: card, bank_redirect, bank_transfer." }, { "name": "ERROR_CREATE_GROUP_PAYMENT_EXCEEDED_MAX_PARTICIPANTS", "description": "The request tried to create a group payment, but there were too many individual payments. The request was rejected. Corrective action: Use 2 to 10 payments." }, { "name": "ERROR_CREATE_GROUP_PAYMENT_INVALID_EXPIRATION", "description": "The request tried to create a group payment, but the expiration was not valid. The request was rejected. Corrective action: For 'expiration', use a Unix timestamp for a time in the future." }, { "name": "ERROR_CREATE_GROUP_PAYMENT_INVALID_PAYMENTS", "description": "The request tried to create a group payment, but the payments were not in the form of an array. The request was rejected. Corrective action: For the 'payments' array, use an array of 'payment' objects." }, { "name": "ERROR_CREATE_GROUP_PAYMENT_MISSING_CURRENCY", "description": "The request tried to create a group payment, but one of the payment methods did not specify a currency. The request was rejected. Corrective action: For all payments, specify the same currency." }, { "name": "ERROR_CREATE_GROUP_PAYMENT_MISSING_PAYMENTS", "description": "The request tried to create a group payment, but the payments were not found. The request was rejected. Corrective action: For the 'payments' array, use an array of 'payment' objects." }, { "name": "ERROR_CREATE_GROUP_PAYMENT_PARTICIPANTS_LESS_THAN_MIN", "description": "The request tried to create a group payment, but there was only one individual payment. The request was rejected. Corrective action: Use 2 to 10 payments." }, { "name": "ERROR_DIFFERENT_COUNTRIES_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "description": "The request tried to create a group payment, but the payment methods in the individual payments were not all from the same country. The request was rejected. Corrective action: For all payments, use payment methods that are supported in the same country." }, { "name": "ERROR_DIFFERENT_CURRENCIES_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "description": "The request tried to create a group payment or replace a failed payment in a group payment, but the individual payments did not all use the same currency. The request was rejected. Corrective action: Use the same currency for all payments." }, { "name": "ERROR_ESCROW_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "description": "The request tried to create a group payment, but one of the payment methods required an escrow. The request was rejected. Corrective action: For all payments, do not use escrow." }, { "name": "ERROR_FX_NOT_SUPPORTED_FOR_GROUP_PAYMENT", "description": "The request tried to create a group payment, but one of the payment methods required currency exchange. The request was rejected. Corrective action: For all payments, do not use currency exchange." }, { "name": "ERROR_GET_GROUP_PAYMENT", "description": "The request attempted an operation that requires a group payment, but the group payment was not found. The request was rejected. Corrective action: Use the ID of a valid group payment, a string starting with 'gp_'." }, { "name": "ERROR_GROUP_PAYMENT_CAN_NOT_BE_CANCELED", "description": "The request tried to cancel a group payment, but the statuses of the individual payments were not all 'ERR' or 'ACT'. The request was rejected. Corrective action: None. Contact Rapyd Client Support." }, { "name": "ERROR_GROUP_PAYMENT_CAN_NOT_BE_REFUNDED", "description": "The request tried to create a refund on a group payment, but the statuses of the individual payments were not all 'ERR' or 'CLO'. The request was rejected. Corrective action: None. Wait until all payments are closed, or contact Client Support." }, { "name": "ERROR_GROUP_PAYMENT_NO_FAILED_PAYMENTS_TO_REPLACE", "description": "The request tried to replace a payment in a group payment, but there were no failed payments to replace. The request was rejected. Corrective action: None. Wait until one of the payments fails." }, { "name": "ERROR_GROUP_PAYMENT_PAYMENT_AMOUNT_EXCEEDS_FAILED_PAYMENTS_TOTAL_AMOUNT", "description": "The request tried to replace a payment in a group payment, but the amount was greater than the total amount of failed payments. The request was rejected. Corrective action: Set 'amount' to the total amount of failed payments." }, { "name": "ERROR_INVALID_GROUP_PAYMENT", "description": "The request attempted an operation that requires a group payment, but the ID of the group payment was not a string. The request was rejected. Corrective action: For 'group_payment', use the ID of a valid group payment, which is a string starting with 'gp_'." }, { "name": "ERROR_MISSING_GROUP_PAYMENT", "description": "The request attempted an operation that requires a group payment, but the group payment was not found. The request was rejected. Corrective action: Use the ID of a valid group payment, a string starting with 'gp_'." }, { "name": "ERROR_REFUND_GROUP_PAYMENT_INVALID_AMOUNT", "description": "The request tried to refund against a group payment, but the amount was not valid. The request was rejected. Corrective action: For 'amount', use a decimal number." } ] }, { "product": "collect", "id": "invoice-object", "type": "type", "name": "Invoice", "description": "An invoice contains a list of charges from a subscription and defines when the payment is due.", "fields": [ { "description": "ID of the Invoice object. String starting with **invoice_**.", "type": [ { "type": "string", "startsWith": "invoice_" } ], "name": "id", "required": true }, { "type": [ { "type": "number" } ], "name": "attempt_count", "description": "Number of payment attempts for this invoice. Integer. After the first attempt, only automatic attempts are included in this count. Response only.", "required": true }, { "type": [ { "type": "boolean" } ], "name": "attempted", "description": "Indicates whether an attempt has been made to pay the invoice automatically. Response only.", "required": true }, { "type": [ { "type": "string" } ], "name": "billing", "description": "Determines the method of collection. Set to **pay_automatically** - Rapyd generates a 'payment' object, then attempts to pay it using the designated payment method.", "required": true }, { "name": "billing_reason", "type": [ { "type": "string", "possibleValues": [ "subscription_cycle", "subscription_create", "manual", "upcoming" ] } ], "description": "The reason for billing. One of the following:\n\n* **subscription_cycle** - A new cycle for the subscription.\n* **subscription_create** - A new subscription has been created.\n* **manual** - Customer was billed manually.\n* **upcoming** - Customer has an upcoming billing invoice.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "The time the invoice was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "type": [ { "type": "string" } ], "name": "currency", "description": "Three-letter ISO 4217 currency code for the currency used in all fields that refer to a monetary amount. Required when the `subscription` field is not provided. If `subscription` field is provided, then the currency defined in the subscription's plan is used.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer that pays this invoice. String starting with **cus_**.\n\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "days_until_due", "type": [ { "type": "number" } ], "description": "Number of days the customer has for paying this invoice. Integer. Relevant when `billing` is **send_invoice**.\nDefault value is 30 days.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the invoice.", "required": true }, { "name": "discount", "type": [ { "type": "object", "id": "discount-object" } ], "description": "Describes the discount that applies to this invoice. The source of the discount is one of the following:\n\\* If the invoice is generated manually, the discount is taken from the Customer object.\n\\* If the invoice is generated automatically from a subscription, the discount is taken from the Subscription object if it is defined there, otherwise it is taken from the Customer object.\n\nFor more information, see [Discount Object](ref:discount-object).", "required": true }, { "name": "due_date", "type": [ { "type": "number" } ], "description": "The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the `days_until_due` field. Relevant when `billing` is **send_invoice**.\nFormat is in [*Unix time*](ref:glossary).", "required": true }, { "name": "lines", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "invoice-item-object" } ] } ], "description": "The individual line items that make up the invoice. These items are added with [Create Invoice](ref:create-invoice) or [Update Invoice](ref:update-invoice).\n\nFor more information, see [Invoice Item Object](ref:invoice-item-object).", "required": true }, { "name": "metadata", "description": "A JSON object defined by the client.", "type": [ { "type": "object" } ], "required": true }, { "name": "next_payment_attempt", "description": "The time at which payment will next be attempted, in [*Unix time*](ref:glossary). Relevant when `billing` is **pay_automatically**.", "type": [ { "type": "number" } ], "required": true }, { "name": "number", "type": [ { "type": "string" } ], "description": "Invoice number, starting with the `invoice_prefix` specified in the Customer object. Response only.", "required": true }, { "name": "payment", "description": "ID of the Payment object that was generated for this invoice. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "payment_fields", "type": [ { "type": "object", "id": "payment-object" } ], "description": "Payment fields of `payment` object. For more information, see [Payment Object](ref:payment-object)", "required": true }, { "name": "payment_method", "type": [ { "type": "string" } ], "description": "Payment method for the invoice. If not provided then payment method is taken from the subscription. If payment method is not provided in the subscription, then payment method is taken from the customer's default payment method.", "required": true }, { "description": "Reserved.", "name": "payout", "type": [ { "type": "string" } ], "required": true }, { "description": "Reserved.", "name": "payout_fields", "type": [ { "type": "object" } ], "required": true }, { "name": "period_end", "type": [ { "type": "string" } ], "description": "Last date in the period covered by the invoice. Response only.", "required": true }, { "name": "period_start", "type": [ { "type": "string" } ], "description": "First date in the period covered by the invoice. Response only.", "required": true }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "description": "Description of the invoice for the customer's credit card statement. Limited to 22 characters.", "required": true }, { "name": "status", "type": [ { "type": "string" } ], "description": "An invoice moves through a series of statuses. See status table below.", "required": true }, { "name": "subscription", "type": [ { "type": "string" } ], "description": "ID of the subscription that generates charges to this customer.", "required": true }, { "name": "subtotal", "type": [ { "type": "number" } ], "description": "Total of all line items before discount and before tax. Decimal. Response only.", "required": true }, { "name": "tax", "type": [ { "type": "number" } ], "description": "The amount of tax charged. Decimal. \n\nThis is calculated as\n**T = R x (S - D)**, where:\n* **T** is the tax.\n* **R** is the tax rate in `tax_percent`.\n* **S** is the subtotal.\n* **D** is the discount.", "required": true }, { "name": "tax_percent", "type": [ { "type": "number" } ], "description": "The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal, up to four decimal places.\n\nRange: 0-100", "required": true }, { "name": "total", "type": [ { "type": "number" } ], "description": "Total after discount and tax. Decimal.", "required": true } ] }, { "product": "collect", "parent": "invoice-object", "id": "create-invoice", "type": "request", "name": "CreateInvoiceRequest", "description": "Use the POST method to create an invoice manually. After you create the invoice with this method, create invoice items and assign them to the invoice with [Create Invoice Item](ref:create-invoice-item). \n\nThis method triggers the **Invoice Created** webhook. This webhook contains the same information as the response.\n\n> **Note:** Clients who have PCI clearance can use card payment methods for an invoice.", "method": "POST", "path": "/v1/invoices", "params": [], "body": [ { "name": "billing", "type": [ { "type": "string" } ], "required": false, "description": "Determines the method of collection: **pay_automatically** or **send_invoice**. Default is **pay_automatically**." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency used for this invoice. Uppercase." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the customer. String starting with **cus_**." }, { "name": "days_until_due", "type": [ { "type": "number" } ], "required": false, "description": "The number of days until the due date." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the invoice." }, { "name": "due_date", "type": [ { "type": "number" } ], "required": false, "description": "The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the `days_until_due` field. Format is in [*Unix time*](ref:glossary)." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment_fields", "type": [ { "type": "object" } ], "required": false, "description": "Payment fields of `payment` object." }, { "name": "payment_method", "type": [ { "type": "string" } ], "required": false, "description": "Payment method for the invoice." }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "Description of the invoice for the customer's credit card statement. Limited to 22 characters." }, { "name": "subscription", "type": [ { "type": "string" } ], "required": false, "description": "ID of the subscription that is the basis for this invoice." }, { "name": "tax_percent", "type": [ { "type": "number" } ], "required": false, "description": "The tax rate, defined as a percentage." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "update-invoice", "type": "request", "name": "UpdateInvoiceRequest", "description": "Use the POST method to change or modify an invoice. You can modify the invoice when its status is **draft**.\n\nThis method triggers the **Invoice Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/invoices/{invoice}", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice you want to update." } ], "body": [ { "name": "days_until_due", "type": [ { "type": "number" } ], "required": false, "description": "The number of days after the creation of the invoice until payment is due." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the invoice." }, { "name": "due_date", "type": [ { "type": "number" } ], "required": false, "description": "The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the `days_until_due` field. Format is in [*Unix time*](ref:glossary)." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment_fields", "type": [ { "type": "object" } ], "required": false, "description": "Payment fields of `payment` object." }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "Description of the invoice for the customer's credit card statement. Limited to 22 characters." }, { "name": "tax_percent", "type": [ { "type": "number" } ], "required": false, "description": "The tax rate, defined as a percentage. You cannot change this value after payment on the invoice has been attempted or forgiven." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "finalize-invoice", "type": "request", "name": "FinalizeInvoiceRequest", "description": "Use the POST method to finalize an invoice.\n\nInvoices are initially created with a **draft** status, and this is the only state in which an invoice can be edited or deleted.\n\nWhen an invoice is ready to be paid, it should be finalized. This set its status to **open**.\n\nSubscriptions automatically create draft invoices during each billing cycle, and are then automatically finalized after an hour. \n \nWhen an invoice is finalized, it can no longer be deleted and its final status can be one of the following:\n* Paid\n* Uncollectible\n* Void\n\nThis method triggers the **Invoice Finalized** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/invoices/{invoice}/finalize", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice you want to pay." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "pay-invoice", "type": "request", "name": "PayInvoiceRequest", "description": "Use the POST method to make a payment against an invoice.\n\nThis method triggers the **Invoice Payment Created** webhook. This webhook contains the same information as the response.\n\nThe following asynchronous webhook provides information about later changes to the Invoice object:\n* [Webhook - Invoice Payment Succeeded](ref:webhook-invoice-payment-succeeded)", "method": "POST", "path": "/v1/invoices/{invoice}/pay", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice you want to pay." } ], "body": [ { "name": "payment_method", "type": [ { "type": "string" } ], "required": false, "description": "Payment method for the invoice." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "void-invoice", "type": "request", "name": "VoidInvoiceRequest", "description": "Use the POST method to set the invoice to the **void** status. Void invoices are similar to deleted invoices, but their records are kept for accounting purposes.", "method": "POST", "path": "/v1/invoices/{invoice}/void", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice you want to pay." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "mark-invoice-uncollectible", "type": "request", "name": "MarkInvoiceUncollectibleRequest", "description": "Use the POST method to set the invoice to the **uncollectible** status. This status indicates that the invoice cannot be paid by the customer.", "method": "POST", "path": "/v1/invoices/{invoice}/mark_uncollectible", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice you want to pay." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "retrieve-invoice", "type": "request", "name": "RetrieveInvoiceRequest", "description": "Use the GET method to retrieve the basic data of an invoice, with individual invoice lines.", "method": "GET", "path": "/v1/invoices/{invoice}", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "The ID of the invoice that you want to retrieve." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "retrieve-invoice-lines-from-invoice", "type": "request", "name": "RetrieveInvoiceLinesFromInvoiceRequest", "description": "Use the GET method to retrieve invoice lines from an invoice. Invoice lines are subscription items or invoice items.", "method": "GET", "path": "/v1/invoices/{invoice}/lines", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "retrieve-upcoming-invoice", "type": "request", "name": "RetrieveUpcomingInvoiceRequest", "description": "Use the GET method to retrieve a preview of the basic data of the upcoming invoice for a customer, with individual invoice lines. To get the invoice lines of the invoice, use [Retrieve Invoice Lines from Invoice](ref:retrieve-invoice-lines-from-invoice).\n\nThe response generated cannot be used to generate a payment authorization.", "method": "GET", "path": "/v1/invoices/upcoming", "params": [], "body": [], "headers": [], "query": [ { "name": "customer", "type": [ { "type": "string" } ], "required": true, "description": "ID of the customer whose invoice you want to retrieve." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency used for this bank account. Required only when subscription is not provided. Uppercase." } ] }, { "product": "collect", "parent": "invoice-object", "id": "retrieve-invoice-lines-from-upcoming-invoice", "type": "request", "name": "RetrieveInvoiceLinesFromUpcomingInvoiceRequest", "description": "Use the GET method to retrieve invoice lines from the upcoming invoice for a customer. If a customer has more than one subscription, this method retrieves the invoice lines of the invoice that are due first.\n**Note:** This method is relevant to invoices that are automatically generated out of subscriptions.", "method": "GET", "path": "/v1/invoices/upcoming/lines", "params": [], "body": [], "headers": [], "query": [ { "name": "customer", "type": [ { "type": "string" } ], "required": true, "description": "ID of the customer whose invoice you want to retrieve." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency. Required when the invoice is not linked to a specific subscription. Uppercase." } ] }, { "product": "collect", "parent": "invoice-object", "id": "list-invoices", "type": "request", "name": "ListInvoicesRequest", "description": "Use the GET method to retrieve a list of all invoices.", "method": "GET", "path": "/v1/invoices", "params": [], "body": [], "headers": [], "query": [ { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the invoice created before the first invoice you want to retrieve." }, { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the invoice created after the last invoice you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of invoices to return. Range: 1-100. Default is 10." }, { "name": "customer", "type": [ { "type": "string" } ], "required": false, "description": "ID of the customer." }, { "name": "date", "type": [ { "type": "string" } ], "required": false, "description": "Date that the invoice was created." }, { "name": "due_date", "type": [ { "type": "number" } ], "required": false, "description": "The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the `days_until_due` field. Format is in [*Unix time*](ref:glossary)." }, { "name": "subscription", "type": [ { "type": "string" } ], "required": false, "description": "ID of the subscription." } ] }, { "product": "collect", "parent": "invoice-object", "id": "delete-invoice", "type": "request", "name": "DeleteInvoiceRequest", "description": "Use the DELETE method to delete an invoice. \n\nYou can delete an invoice when `status` is **draft**.\n\nThis method triggers the **Invoice Deleted** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/invoices/{invoice}", "params": [ { "name": "invoice", "type": [ { "type": "string" } ], "required": true, "description": "ID of the invoice you want to delete." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "invoice-object", "id": "invoice-errors", "type": "enum", "name": "InvoiceError", "values": [ { "name": "ERROR_DELETE_INVOICE", "description": "The request tried to delete an invoice, but the operation failed. Corrective action: Check all input fields, and verify that the invoice exists and was not already deleted." }, { "name": "ERROR_DELETE_NOT_DRAFT_INVOICE", "description": "The request tried to delete an invoice, but the invoice is not in 'draft' status. Only a draft invoice can be deleted. The request was rejected. Corrective action: None. Determine why an attempt was made to delete an invoice that is not in ‘draft’ status." }, { "name": "ERROR_GET_INVOICE", "description": "The request tried to retrieve an invoice, but the invoice was not found. The request was rejected. Corrective action: Use a valid invoice ID." }, { "name": "ERROR_MARK_UNCOLLECTIBLE_NOT_OPEN_INVOICE", "description": "The request tried to mark an invoice as uncollectible, but the invoice status was not 'open'. The request was rejected. Corrective action: None. Determine why the invoice was not in 'open' status." }, { "name": "ERROR_PAY_INVOICE", "description": "The request tried to pay an invoice, but the invoice was not found. The request was rejected. Corrective action: Use the ID of a valid invoice." }, { "name": "ERROR_PAY_INVOICE_PAYMENT", "description": "The request attempted to pay invoice, but the invoice type is not payment. The request was rejected." }, { "name": "ERROR_UPDATE_NOT_DRAFT_INVOICE", "description": "The request tried to a update an invoice but the invoice is not draft. Can only update draft invoice. The request was rejected." }, { "name": "ERROR_UPDATE_PAYOUT_INVOICE", "description": "The request tried to update an invoice, but the invoice was not a payment invoice. The request was rejected. Corrective action: Set 'type' to 'payment'." }, { "name": "ERROR_VOID_NOT_UNCOLLECTIBLE_OR_OPEN_INVOICE", "description": "The request tried to a void an invoice but the invoice is draft or paid. Can only void open or uncollectible invoice. The request was rejected." }, { "name": "ERROR_VOID_PAYOUT_INVOICE", "description": "The request tried to set status 'void' to an invoice but the invoice type is 'payout'. Can only set status 'void' 'payment' invoice. The request was rejected." }, { "name": "INVALID_DAYS_UNTIL_DUE_AND_BILLING", "description": "\"The request tried to update an invoice, but the 'billing' body parameter was set to 'pay_automatically', and 'days_until_due' field was set. 'days_until_due' is relevant only when 'billing' is set to 'send_invoice'. The request was rejected. Corrective action: Set 'billing' to 'send_invoice', or set 'days_until_due' to null." }, { "name": "INVALID_DUE_DATE", "description": "The request tried to set or update the due date of an invoice, but the value was not valid. The request was rejected. Corrective action: Set the 'due_date' body parameter to a valid Unix timestamp in the future." }, { "name": "INVALID_INVOICE_CURRENCY", "description": "The request tried to add an invoice item to an invoice, but the currency specified in the request was not the same as the currency defined for other existing items in the invoice. The request was rejected. Corrective action: Use the same currency for all invoice items in the invoice." }, { "name": "INVALID_INVOICE_CUSTOMER", "description": "The request attempted an operation that requires a customer, but the customer specified in the request was not the same as the customer defined for the subscription. The request was rejected. Corrective action: For the invoice and all of its invoice items, use the customer identified in the subscription." }, { "name": "INVALID_INVOICE_ID", "description": "The request attempted an operation that requires an invoice, but the invoice was not found. The request was rejected. Corrective action: Use the ID of a valid invoice." }, { "name": "INVALID_INVOICE_ID_AND_SUBSCRIPTION_ID", "description": "The request tried to create an invoice item, but the request attempted to link it to both a subscription and an invoice. The request was rejected. Corrective action: Link the invoice item to an invoice or to a subscription, but not both." }, { "name": "INVALID_SUBSCRIPTION_TRIAL_END", "description": "The request tried to retrieve the upcoming invoice for a customer, but the 'trial_end' body parameter was set in the subscription and there were no invoice items in the 'lines' array. The request was rejected. Corrective action: Add valid items to the 'lines' array in the subscription or the invoice." } ] }, { "product": "collect", "id": "order-object", "type": "type", "name": "Order", "description": "The Order object represents a single order of goods.", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "order_" } ], "description": "Unique ID of the Order object. If the merchant does not define an ID, Rapyd generates a string starting with **order_**.", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "\\* **In request:** In each item of type **sku**, the cost of one individual item, in units specified in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.\n\n\\* **In response:** Total amount of the order, the sum of the amount of the 'shipping' items, plus the `amount` of the tax, plus `amount` times `quantity` of each of the 'sku' items. Decimal. Response only.", "required": true }, { "name": "amount_returned", "type": [ { "type": "number" } ], "description": "Total amount of returns against the order. Decimal. Response only.", "required": true }, { "name": "coupon", "type": [ { "type": "string" } ], "description": "ID of a discount coupon that is applied against this order. The coupon `duration` must be **once**.", "required": true }, { "name": "created", "type": [ { "type": "number" } ], "description": "When the order was created, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the 'item' objects. Uppercase.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer. String starting with **cus_**.", "required": true }, { "name": "discount", "type": [ { "type": "string" } ], "description": "Contains information about the coupon that applies to the subscription. Response only.\n\nAdding a discount is a 2-step process:\n1. [Create Coupon](ref:create-coupon), which returns a coupon ID. \n2. Add the coupon ID to the `coupon` field of the order with [Create an Order](ref:create-an-order) or [Update Order](ref:update-order).\n\nFor more information, see [Discount Object](ref:discount-object).", "required": true }, { "name": "email", "type": [ { "type": "string" } ], "description": "Email address of the customer.", "required": true }, { "type": [ { "type": "string" } ], "name": "external_coupon_code", "description": "ID for the coupon, defined by the merchant.", "required": true }, { "name": "items", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Each item describes one charge in this invoice. There must be one item of `type` = **shipping** and at least one item of `type` = **sku**.\n\nSee ***Items Object***, below.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "payment", "type": [ { "type": "object", "id": "payment-object" } ], "description": "Describes the collection efforts being made against this order. Read-only. See [Payment Object](ref:payment-object).", "required": true }, { "name": "payment_method", "type": [ { "type": "string", "startsWith": "card_" } ], "description": "Payment method ID. String starting with **card_** or **other_**.\n\nIf not specified in this field, the payment method is the default payment method specified for the customer.\n\nTo create a payment method token, use the [Add Payment Method](ref:add-payment-method) method.", "required": true }, { "name": "returns", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "A list of the returns charged against this order.", "required": true }, { "name": "shipping_address", "type": [ { "type": "object", "id": "address-object" } ], "description": "Address to receive the shipment. For more information, see [Address Object](ref:address-object).", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "created", "pending", "paid", "canceled", "fulfilled", "returned" ] } ], "description": "Indicates the status of the order. One of the following:\n* **created** - Created.\n* **pending** - The collection process has been started.\n* **paid** - Paid in full.\n* **canceled** - The total amount of returns against this order equal the total amount of the order.\n* **fulfilled** - The products have been delivered to the customer.\n* **returned** - A return has been processed against this order.", "required": true }, { "name": "status_transitions", "type": [ { "type": "object", "fields": [ { "name": "canceled", "type": [ { "type": "unknown" } ] }, { "name": "fulfilled", "type": [ { "type": "unknown" } ] }, { "name": "paid", "type": [ { "type": "unknown" } ] }, { "name": "pending", "type": [ { "type": "unknown" } ] }, { "name": "returned", "type": [ { "type": "unknown" } ] } ] } ], "description": "Records the number of transitions to each possible status. Each field contains an integer. Read-only. Contains the following fields:\n* `canceled`\n* `fulfilled`\n* `paid`\n* `pending`\n* `returned`", "required": true }, { "name": "tax_percent", "type": [ { "type": "number" } ], "description": "Percentage of tax to charge. Decimal 0-100, up to four decimal places.", "required": true }, { "name": "updated", "type": [ { "type": "number" } ], "description": "Time the order was last updated, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "description": "Merchant-defined ID for the order.", "type": [ { "type": "string" } ], "name": "upstream_id", "required": true } ] }, { "product": "collect", "parent": "order-object", "id": "create-an-order", "type": "request", "name": "CreateAnOrderRequest", "description": "Use the POST method to create an order of goods. For services, see [Create Subscription](ref:create-subscription-object).\n\nThe payment method used in the process is the default payment method assigned to the customer. See [Pay an Order](ref:pay-an-order).\n\nThis method triggers the **Order Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/orders", "params": [], "body": [ { "name": "coupon", "type": [ { "type": "string", "startsWith": "coupon_" } ], "required": false, "description": "ID of a coupon that is applied against this order. String starting with **coupon_**. The coupon `duration` must be **once**." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true, "description": "ID of the customer. String starting with **cus_**." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in the objects in the 'items' list. Uppercase." }, { "name": "email", "type": [ { "type": "string" } ], "required": true, "description": "Email address of the customer." }, { "name": "items", "type": [ { "type": "string" } ], "required": true, "description": "Array of line items." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "shipping_address", "type": [ { "type": "object", "id": "address-object" } ], "required": false, "description": "Address to receive the shipment. `name` and `line1` are required. See [Address Object](ref:address-object)." }, { "name": "tax_percent", "type": [ { "type": "number" } ], "required": true, "description": "Percentage of tax to charge. Decimal." }, { "name": "upstream_id", "type": [ { "type": "string" } ], "required": false, "description": "Merchant-defined ID for the order. If the merchant does not define an ID, Rapyd generates it." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "order-object", "id": "update-order", "type": "request", "name": "UpdateOrderRequest", "description": "Use the POST method to change or modify an order. You can make the following changes:\n> \\* When `status` is **created**: `coupon`, `metadata` or `tax_percent` fields.\n> \\* When `status` is **pending**, **paid**, or **fulfilled**: `metadata` or `status` fields.\n\nWhen the customer completes a payment, the merchant must change the `status` from **pending** to **paid**.\n\nThis method triggers the **Order Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/orders/{order}", "params": [ { "name": "order", "type": [ { "type": "string" } ], "required": true, "description": "ID of the order." } ], "body": [ { "name": "coupon", "type": [ { "type": "string" } ], "required": false, "description": "ID of a discount coupon that is applied against this order. The coupon `duration` must be **once**. Can be changed when status is **created**." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "status", "type": [ { "type": "string" } ], "required": false, "description": "Indicates the status of the order. Can be changed when status is **pending**, **paid**, or **fulfilled**." }, { "name": "tax_percent", "type": [ { "type": "number" } ], "required": false, "description": "Percentage of tax to charge. Decimal. Can be changed when status is **created**." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "order-object", "id": "pay-an-order", "type": "request", "name": "PayAnOrderRequest", "description": "Use the POST method to pay an order. This method starts the collection process and changes the `status` of the order from **created** to **pending**. If the payment method is card, the status changes automatically from **pending** to **paid** when the payment is captured.", "method": "POST", "path": "/v1/orders/{order}/pay", "params": [ { "name": "order", "type": [ { "type": "string", "startsWith": "order_" } ], "required": true, "description": "ID of the order to pay. String starting with **order_**." } ], "body": [ { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment_method", "type": [ { "type": "number" } ], "required": false, "description": "ID of the payment method. String starting with **card_** or **other_**. If not specified, the payment method is the `default_payment_method` of the customer." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "order-object", "id": "retrieve-an-order", "type": "request", "name": "RetrieveAnOrderRequest", "description": "Use the GET method to retrieve the details of an order.", "method": "GET", "path": "/v1/orders/{order}", "params": [ { "name": "order", "type": [ { "type": "string", "startsWith": "order_" } ], "required": true, "description": "ID of the order. String starting with **order_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "order-object", "id": "list-orders", "type": "request", "name": "ListOrdersRequest", "description": "Use the GET method to retrieve a list of all orders.", "method": "GET", "path": "/v1/orders", "params": [], "body": [], "headers": [], "query": [ { "name": "ending_before", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the order created after the last order you want to retrieve." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of orders to return. Range: 1-100. Default is 10." }, { "name": "starting_after", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the order created before the first order you want to retrieve." } ] }, { "product": "collect", "parent": "order-object", "id": "order-errors", "type": "enum", "name": "OrderError", "values": [ { "name": "ERROR_GET_LIST_ORDER", "description": "The request tried to retrieve an order for a customer or a return on an order, but the order was not found. The request was rejected. Corrective action: Use a valid order ID." }, { "name": "ERROR_GET_ORDER", "description": "The request attempted an operation that requires an order, but the order was not found. The request was rejected. Corrective action: Use the ID of a valid order, a string starting with ‘order’." }, { "name": "ERROR_GET_ORDER_RETURN", "description": "The request tried to retrieve a return on an order, but the order was not found. The request was rejected. Corrective action: Use a valid order ID." }, { "name": "ERROR_INVALID_COUPON_TYPE", "description": "The request tried to add a coupon to an order, but the 'type' of the coupon was not 'once'. The request was rejected. Corrective action: Choose a coupon that has 'type' set to 'once.'" }, { "name": "ERROR_INVALID_ORDER_CURRENCY", "description": "The request tried to create an order, but the currency of the order items did not match the currency of the order. The request was rejected. Corrective action: For 'currency' in each object in the 'items' array, use the currency of the order." }, { "name": "ERROR_INVALID_ORDER_SHIPPING_ADDRESS", "description": "The request tried to create an order, but the order contained order items that are marked 'shippable,' and there was no shipping address. When an order contains shippable items, the shipping address is required. The request was rejected. Corrective action: Add a shipping address." }, { "name": "ERROR_MISSING_CUSTOMER", "description": "The request tried to create an order, but the customer was not found. The request was rejected. Corrective action: For 'customer', provide the ID of a valid customer, a string starting with 'customer'." }, { "name": "ERROR_MISSING_ORDER_EMAIL", "description": "The request tried to create an order, but the 'email' of the customer was not found in the order or the 'customer' object. The request was rejected. Corrective action: Add the customer's email to the customer or the order." }, { "name": "ERROR_MISSING_ORDER_ITEMS", "description": "The request tried to create an order or a return against an order, but no items were added. An order requires at least one order item, and a return requires at least one return item. The request was rejected. Corrective action: Add one or more items." }, { "name": "ERROR_MISSING_PRODUCT_TOKEN", "description": "The request tried to create an order, but the SKU for an item was not found. The request was rejected. Corrective action: Use a valid SKU ID in the 'parent' field of the item." }, { "name": "ERROR_ORDER_COUPON_FIELD_NOT_UPDATABLE", "description": "The request tried to update a coupon for an order, but the order status was not 'new'. An order can only be updated when the status is 'new.' The request was rejected. Corrective action: Create a new order and add the coupon to it." }, { "name": "ERROR_ORDER_COUPON_INVALID_CURRENCY", "description": "The request tried to add an 'amount off' coupon to an order, but the curency was not recognized. The request was rejected. Corrective action: Set 'coupon' to the ID of a coupon that has 'currency' set to the same currency as the order." }, { "name": "ERROR_ORDER_INVALID_EMAIL", "description": "The request tried to create an order, but the format of the email address was incorrect, or no email address was found for the order or for the customer. The request was rejected. Corrective action: Use a valid email address for the customer or the order." }, { "name": "ERROR_ORDER_INVALID_STATUS", "description": "The request tried to update the status of an order, but the status offered was not valid. The request was rejected. Corrective action: Set the status to one of the valid values." }, { "name": "ERROR_ORDER_INVALID_TAX_PERCENT", "description": "The request tried to set the 'tax_percent' field of an order to a negative number. The request was rejected. Corrective action: Set the tax percent to zero or a positive number." }, { "name": "ERROR_ORDER_ITEM_INVALID_AMOUNT_NUMBER", "description": "The request tried to create an order, but the amount of an item was zero or negative. The amount must be a positive number. The request was rejected. Corrective action: For 'amount' in each object in the 'items' array, use a positive decimal number." }, { "name": "ERROR_ORDER_ITEM_INVALID_DISCOUNT", "description": "The request tried to process an order item that was subject to a discount, but the discount was based on a coupon that was not found. The request was rejected. Corrective action: Delete the discount from the order, then add a valid coupon." }, { "name": "ERROR_ORDER_ITEM_INVALID_TYPE", "description": "The request tried to create an order, but the 'type' of an order item was not recognized. The request was rejected. Corrective action: Set 'type' to one of the following values: 'sku' or 'shipping'." }, { "name": "ERROR_ORDER_ITEM_MISSING_PARENT", "description": "The request tried to create an order, but a coupon or sku object was not found. The request was rejected. Corrective action: For each order item of type 'sku' in the 'items' array, use a valid SKU ID in the 'parent' field. For each order item of type 'coupon', use a valid coupon ID in the 'parent' field." }, { "name": "ERROR_ORDER_MISSING_CURRENCY", "description": "The request tried to create an order, but the 'currency' body parameter was blank or not found. The request was rejected. Corrective action: Use the correct 3-letter ISO 4217 code for the currency." }, { "name": "ERROR_ORDER_MISSING_SHIPPING_ITEM", "description": "The request tried to create an order, but the list of items in the order did not contain an item for shipping. The request was rejected. Corrective action: Add an item with 'type' set to 'shipping'. If the shipping is free, set 'amount' to 0." }, { "name": "ERROR_ORDER_MISSING_SKU_ITEM", "description": "The request tried to create an order, but the list of items in the order did not contain an SKU item. The request was rejected. Corrective action: Add an item with 'type' set to 'sku'." }, { "name": "ERROR_ORDER_SAME_SKU_PRESENT_IN_MORE_THAN_ONE_ORDER_ITEM", "description": "The request tried to create an order, but two or more order items had the same SKU. Each SKU object can appear only one time in the list of items. The request was rejected. Corrective action: Combine the quantities of all line items that refer to the same SKU object." }, { "name": "ERROR_ORDER_SHIPPING_ITEM_INVALID_QUANTITY", "description": "The request tried to create an order, but the quantity of shipping items was not correct. The request was rejected. Corrective action: In the list of items, set the 'quantity' field in the 'shipping' item to 1." }, { "name": "ERROR_ORDER_STATUS_DOES_NOT_ALLOW_RETURNS", "description": "The request tried to create a return against an order, but the status was 'created', 'pending' or 'canceled'. The request was rejected. Corrective action: Check why an attempt was made to create a return against an order that was already fully returned or never delivered." }, { "name": "ERROR_ORDER_TAX_FIELD_NOT_UPDATABLE", "description": "The request tried to update the 'tax_percent' body parameter of an order, but the order status was not 'new'. An order can only be updated when the status is 'new.' The request was rejected. Corrective action: Create a new order and add the correct value to the 'tax_percent' field." }, { "name": "ERROR_PAY_ORDER", "description": "The request tried to pay an order, but the order was already paid. The request was rejected. Corrective action: None. Determine why multiple attempts were made to pay the same order." }, { "name": "ERROR_PAY_ORDER_COMPLETED_WITHOUT_ORDER_STATUS_UPDATE", "description": "The request to pay the order was successful, but the status of the order was not updated. Please contact Rapyd customer support for more information." }, { "name": "ERROR_PAYMENT_COMPLETED_WITHOUT_ORDER_STATUS_UPDATE", "description": "The request to complete the payment was successful, but the status of the order was not updated. Please contact Rapyd customer support for more information." }, { "name": "IDENTITY_PROOF_REQUIRED", "description": "The request tried to create an order, but validation of the customer's identity was required and was not found. The request was rejected. Corrective action: Verify the customer's identity." } ] }, { "product": "collect", "id": "checkout-page-object", "type": "type", "name": "CheckoutPage", "description": "A Rapyd Checkout page enables a merchant to create payments for all available payment methods. The page appears directly to the merchant's customer. It can be configured as a standalone page or an i-frame inside the client's own web page. \n\nFor more information, see [Rapyd Checkout](doc:rapyd-checkout-overview).", "fields": [ { "name": "id", "type": [ { "type": "string", "startsWith": "checkout_" } ], "description": "ID of the Rapyd checkout page. String starting with **checkout_**.", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount of the payment, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.", "required": true }, { "name": "cancel_checkout_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected when the customer closes the checkout page before completing the payment. This page can be set dynamically for each generated checkout page as it overrides the fallback URL that was set in the Client Portal.\n\nDoes not support localhost URLs.", "required": true }, { "description": "Describes the cart items that the customer is purchasing. These items are displayed at the checkout page. Contains the following fields for each cart item:\n\\* `name` - The name of the item. Required.\n\\* `amount` - The price of the item in the currency defined in `currency`. Required.\n\\* `quantity` - The quantity of the item. Required.\n\\* `image` - The image that appears in the checkout page for this item.", "name": "cart_items", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "fields": [ { "name": "name", "type": [ { "type": "unknown" } ] }, { "name": "amount", "type": [ { "type": "unknown" } ] }, { "name": "quantity", "type": [ { "type": "unknown" } ] }, { "name": "image", "type": [ { "type": "unknown" } ] } ] } ] } ], "required": true }, { "name": "complete_auto_redirect", "type": [ { "type": "boolean" } ], "description": "Determines whether to redirect to `complete_checkout_url` when the customer is finished with the online checkout page. One of the following:\n\\* **true** - Redirect to display the page in the URL specified in `complete_checkout_url`.\n\\* **false** - Display the default Thank You page. This is the default.", "required": true }, { "name": "complete_checkout_auto_redirect", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "complete_checkout_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected when checkout is successful. This page can be set dynamically for each generated checkout page as it overrides the fallback URL that was set in the Client Portal.\n\nDoes not support localhost URLs.", "required": true }, { "name": "complete_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected after completing the payment instructions on the third party site.\n\nRelevant to bank redirect payment methods.\n\nDoes not support localhost URLs.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.\n\nTo determine the code for a country, see [List Countries](ref:list-countries).", "required": true }, { "name": "country_name", "type": [ { "type": "string" } ], "description": "Name of the country in English.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Defines the currency for the amount received by the seller (merchant). Three-letter ISO 4217 code.\n\nIn FX transactions, when `fixed_side` is **buy**, it is the currency received by the merchant. When `fixed_side` is **sell**, it is the currency charged to the buyer.", "required": true }, { "name": "custom_elements", "type": [ { "type": "object", "id": "custom-elements-object" } ], "description": "Describes customizations of the page as it appears to the customer. See [Custom Elements Object](ref:custom-elements-object).", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer. String starting with **cus_**. When used, the customer has the option to save card details for future purchases.", "required": true }, { "name": "customer_default_payment_method", "type": [ { "type": "object" } ], "description": "The customer's default payment method.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the payment transaction.", "required": true }, { "name": "error_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected after an error occurs on the third-party site.\n\nRelevant to bank redirect payment methods.\n\nDoes not support localhost URLs.", "required": true }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is paid into. String starting with **ewallet_**.", "required": true }, { "name": "expiration", "description": "Time when the payment expires if it is not completed, in [*Unix time*](ref:glossary). When both `expiration` and `payment_expiration` are set, the payment expires at the earlier time. Default is 14 days after creation of the checkout page.", "type": [ { "type": "number" } ], "required": true }, { "type": [ { "type": "string", "possibleValues": [ "buy", "sell" ] } ], "name": "fixed_side", "description": "Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). \nOne of the following values:\n\\* **buy** - The checkout page shows the currency that the seller (merchant) receives for goods or services. This is the default. For example, a US-based merchant wants to charge 100 USD. The buyer (customer) pays the amount in MXN that converts to 100 USD.\n\\* **sell** - The checkout page shows the currency that the buyer is charged with to purchase goods or services from the seller. For example, a US-based merchant wants to charge a buyer 2,000 MXN and will accept whatever amount in USD that is converted from 2,000 MXN.", "required": true }, { "name": "language", "type": [ { "type": "string" } ], "description": "Determines the default language of the hosted page. \nThe values are documented in [Hosted Page Language Support](ref:hosted-page-language-support).", "required": true }, { "name": "merchant_alias", "description": "Reserved. Default is 'Rapyd'.", "type": [ { "type": "string" } ], "required": true }, { "name": "merchant_color", "type": [ { "type": "string" } ], "description": "Color of the action button on the hosted page. Response only.\n\nTo configure this field, use the Client Portal.", "required": true }, { "name": "merchant_customer_support", "type": [ { "type": "object", "fields": [ { "name": "email", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] }, { "name": "phone_number", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contact details for customer support, containing the following fields:\n\\* `email` - Email address.\n\\* `url` - URL for the client's customer support service.\n\\* `phone_number` - Phone number for contacting the client's customer support service.\nResponse only.\n\nTo configure these fields, use the Client Portal.", "required": true }, { "name": "merchant_logo", "type": [ { "type": "string" } ], "description": "URL for the image of the client's logo.", "required": true }, { "name": "merchant_reference_id", "description": "Identifier for the transaction. Defined by the merchant. Can be used for reconciliation.", "type": [ { "type": "string" } ], "required": true }, { "name": "merchant_website", "type": [ { "type": "string" } ], "description": "URL of the client's website.", "required": true }, { "name": "metadata", "description": "A JSON object defined by the client.", "type": [ { "type": "object" } ], "required": true }, { "name": "page_expiration", "type": [ { "type": "number" } ], "description": "End of the time when the customer can use the checkout page, in [*Unix time*](ref:glossary).\nIf `page_expiration` is not set, the checkout page expires 14 days after creation. Range: 1 minute to 30 days.", "required": true }, { "name": "payment_expiration", "type": [ { "type": "number" } ], "description": "Length of time for the payment to be completed after it is created, measured in seconds. When both `expiration` and `payment_expiration` are set, the payment expires at the earlier time.", "required": true }, { "name": "payment_fees", "type": [ { "type": "object", "id": "payment-fees-object" } ], "description": "Describes the fees that can be charged for a payment transaction. See [Payment Fees Object](ref:payment-fees-object).", "required": true }, { "name": "payment_method", "type": [ { "type": "object", "fields": [ { "name": "type", "type": [ { "type": "unknown" } ] }, { "name": "fields", "type": [ { "type": "unknown" } ] }, { "name": "name", "type": [ { "type": "unknown" } ] }, { "name": "address", "type": [ { "type": "unknown" } ] }, { "name": "metadata", "type": [ { "type": "unknown" } ] } ], "id": "get-payment-method-required-fields" } ], "description": "Object that describes the payment method. Contains the following fields:\n\\* `type` - The type of the payment method. Required.\n\\* `fields` - Contains the fields that are required for the payment method. See [Get Payment Method Required Fields](ref:get-payment-method-required-fields).\n\\* `name` - Name of the payment method.\n\\* `address` - 'Address' object that describes the address associated with the payment. See [Address Object](ref:address-object). Do not use an address ID.\n\\* `metadata` - 'Metadata' object defined by the merchant. See [Metadata Object](ref:metadata-object).\n\n**Note:** This behavior is different from [Create Payment](ref:create-payment).", "required": true }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "description": "The type of the payment method. For example, **it_visa_card**.\n\nTo get a list of payment methods for a country, use [List Payment Methods by Country](ref:list-payment-methods-by-country).\n\nSee [Determining Payment Methods](ref:determining-payment-methods).", "required": true }, { "name": "payment_method_type_categories", "type": [ { "type": "array", "arrayTypes": [ { "type": "string", "possibleValues": [ "bank_redirect", "bank_transfer", "card", "cash", "ewallet" ] } ] } ], "description": "A list of the categories of payment method that are supported on the checkout page. The categories appear on the page in the order provided. One or more of the following:\n\\* **bank_redirect**\n\\* **bank_transfer**\n\\* **card**\n\\* **cash**\n\\* **ewallet**\n\nSee [Determining Payment Methods](ref:determining-payment-methods).", "required": true }, { "name": "payment_method_types_exclude", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "List of payment methods that are excluded from display on the checkout page.\n\nSee [Determining Payment Methods](ref:determining-payment-methods).", "required": true }, { "name": "payment_method_types_include", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "List of payment methods that are displayed on the checkout page. The payment methods appear on the page in the order provided.\n\nSee [Determining Payment Methods](ref:determining-payment-methods).", "required": true }, { "name": "redirect_url", "type": [ { "type": "string" } ], "description": "URL of the checkout page that is shown to the customer.", "required": true }, { "name": "requested_currency", "type": [ { "type": "string" } ], "description": "When `fixed_side` is **sell**, it is the currency received by the merchant. \n\nWhen `fixed_side` is **buy**, it is the currency charged to the buyer (customer). The checkout page displays the following information: \n\\* The original amount and currency. \n\\* The converted amount in the requested currency.\n\\* The exchange rate.\n\nThree-letter ISO 4217 code. \n\nRelevant to payments with FX.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "NEW", "ACT", "CLO" ] } ], "description": "Indicates the payment status. One of the following values:\n\\* **NEW** - New payment.\n\\* **ACT** - Active payment.\n\\* **CLO** - Closed payment.", "required": true }, { "name": "timestamp", "type": [ { "type": "number" } ], "description": "Time of creation of the checkout page, in [*Unix time*](ref:glossary). Response only.", "required": true } ] }, { "product": "collect", "id": "custom-elements-object", "type": "type", "name": "CustomElements", "description": "The Custom Elements object contains the following fields:", "fields": [ { "name": "billing_address_collect", "type": [ { "type": "boolean" } ], "description": "Determines whether the customer is asked to fill in the billing address. Relevant when a card payment method is selected.\n\\* **true** - The address fields appear on the checkout page.\n\\* **false** - The address fields appear only if the `country` is **US**, **GB** or **CA**. This is the default.\n**Note:** When the customer already has address details, it will always be displayed.", "required": true }, { "name": "display_description", "type": [ { "type": "boolean" } ], "description": "Determines whether the checkout page displays the payment description.\n\\* **true** - The payment description appears.\n\\* **false** - The payment description does not appear. This is the default.\n\nRelevant when `description` is passed in the 'Create Checkout Page' request.", "required": true }, { "name": "dynamic_currency_conversion", "type": [ { "type": "boolean" } ], "description": "Determines whether the checkout page displays multiple currency options for a payment.\n\\* **true** - Multiple currency options appear.\n\\* **false** - Multiple currency options do not appear. This is the default.\n\nWhen the customer selects the requested currency, the checkout page displays the following information: \n\\* The original amount and currency. \n\\* The converted amount in the requested currency.\n\\* The exchange rate. \n\nRelevant when: \n\\* The 'Create Checkout Page' request passes `requested_currency`.\n\\* `fixed_side` is **buy**. \n\\* One or more payment methods support the values for `currency` and `requested_currency`.", "required": true }, { "name": "merchant_color", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "merchant_currency_only", "type": [ { "type": "boolean" } ], "description": "In a payment with FX where `fixed_side`=**buy**, determines whether the buyer's currency and the exchange rate appear. \nOne of the following:\n\\* **true** - The currency and the exchange rate are hidden.\n\\* **false** - The currency and the exchange rate appear. This is the default.", "required": true }, { "name": "payment_fees_display", "type": [ { "type": "boolean" } ], "description": "Determines whether payment fees appear on the checkout page. \n\\* **true** - Payment fees appear when the `payment_fees` object is set in the 'Create Checkout Page' request. This is the default.\n\\* **false** - Payment fees do not appear.", "required": true }, { "name": "save_card_default", "type": [ { "type": "boolean" } ], "description": "Determines whether the 'save card' checkbox is checked by default.\n\\* **true** - The 'save card' checkbox is checked.\n\\* **false** - The 'save card' checkbox is cleared. This is the default.\n\nRelevant when `customer_id` is passed in the 'Create Checkout Page' request.", "required": true } ] }, { "product": "collect", "parent": "checkout-page-object", "id": "create-checkout-page", "type": "request", "name": "CreateCheckoutPageRequest", "description": "Use the POST method to create a checkout page. \n\nThis step is required before you use a checkout page for the following purposes:\n> \\* Make a payment.\n> \\* Add a payment method to a customer.\n> \\* Modify a customer's payment method.\n> \\* Delete a customer's payment method.\n\n**Notes:**\n* If you create the checkout page without specifying the `customer` field, you must provide full payment method details.\n* The `page_expiration` can be set to a value between 1 minute and 30 days. Values less than 1 minute or more than 30 days will be reset to those limits.\n* If `page_expiration` is not specified, the checkout page expires 14 days after creation.\n* The `amount` must be specified in either `amount` or the `amount` field of each item in the cart.\n* If `ewallet` is specified, the payment is credited to the wallet specified.\n* If you are using this method in the sandbox and are directed to the simulated 3DS authentication page, your `code` is any number.", "method": "POST", "path": "/v1/checkout", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the payment, in units of the currency defined in `currency`. Required if `cart_items` is not used. Decimal." }, { "name": "cancel_checkout_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected when the checkout page is closed before the payment has been completed." }, { "name": "cart_items", "type": [ { "type": "object" } ], "required": false, "description": "Object that describes the cart items that the customer is purchasing. Required if `amount` is not used." }, { "name": "complete_checkout_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected when checkout is successful. This page usually appears after the user clicks the **Finish** button, and can be set dynamically for each generated checkout." }, { "name": "complete_payment_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected when payment is successful. Relevant to bank redirect payment methods." }, { "name": "country", "type": [ { "type": "string" } ], "required": true, "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Defines the currency for the amount. Three-letter ISO 4217 code. For FX transactions, see [Checkout Page Object](ref:checkout-page-object)." }, { "name": "custom_elements", "type": [ { "type": "object", "id": "custom-elements-object" } ], "required": false, "description": "Conditions for displaying additional parameters on the checkout page. See [Custom Elements Object](ref:custom-elements-object)." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "ID of the 'customer' object. String starting with **cus_**. When used, the customer has the option to save card details for future purchases." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the payment." }, { "name": "error_payment_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected when payment is not successful. Relevant to bank redirect payment methods." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the wallet that the money is paid into. String starting with **ewallet_**." }, { "name": "expiration", "type": [ { "type": "string" } ], "required": false, "description": "Time when the payment expires if it is not completed, in [*Unix time*](ref:glossary)." }, { "name": "fixed_side", "type": [ { "type": "string" } ], "required": false, "description": "Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). One of the following values: **sell** or **buy**." }, { "name": "language", "type": [ { "type": "string" } ], "required": false, "description": "Determines the default language of the hosted page." }, { "name": "merchant_currency_only", "type": [ { "type": "boolean" } ], "required": false, "description": "In a payment with FX where `fixed_side`=**buy**, determines whether the buyer's currency and the exchange rate appear." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "Identifier for the transaction. Defined by the merchant." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "page_expiration", "type": [ { "type": "number" } ], "required": false, "description": "End of the time when the customer can use the Checkout page, in [*Unix time*](ref:glossary)." }, { "name": "payment_expiration", "type": [ { "type": "string" } ], "required": false, "description": "Length of time for the payment to be completed after it is created, measured in seconds." }, { "name": "payment_fees", "type": [ { "type": "object" } ], "required": false, "description": "Describes the fees that can be charged for a payment transaction." }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "required": false, "description": "The type of the payment method." }, { "name": "payment_method_type_categories", "type": [ { "type": "string" } ], "required": false, "description": "Category of payment method: **bank_redirect**, **bank_transfer**, **card**, **cash**, **ewallet**." }, { "name": "payment_method_types_exclude", "type": [ { "type": "string" } ], "required": false, "description": "List of payment methods that are excluded from display on the checkout page. Array of strings." }, { "name": "payment_method_types_include", "type": [ { "type": "string" } ], "required": false, "description": "List of payment methods that are displayed on the checkout page. Array of strings." }, { "name": "requested_currency", "type": [ { "type": "string" } ], "required": false, "description": "When `fixed_side` is **sell**, it is the currency received by the merchant. When `fixed_side` is **buy**, it is the currency charged to the buyer (customer). Three-letter ISO 4217 code." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "checkout-page-object", "id": "retrieve-checkout-page", "type": "request", "name": "RetrieveCheckoutPageRequest", "description": "Use the GET method to retrieve a checkout page.", "method": "GET", "path": "/v1/checkout/{checkout}", "params": [ { "name": "checkout", "type": [ { "type": "string" } ], "required": true, "description": "ID of the checkout page object. String starting with 'checkout_'." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "checkout-page-object", "id": "checkout-errors", "type": "enum", "name": "CheckoutError", "values": [ { "name": "ERROR_CHECKOUT_COUNTRY_CURRENCY_MISMATCH", "description": "The request tried to create a checkout page, but there is no payment method that is supported in the country for the currency provided. The request was rejected. Corrective action: Use a different currency or country." }, { "name": "ERROR_CHECKOUT_PAGE_PAYMENT_METHOD_TYPE_CATEGORIES_VALUE_NOT_VALID", "description": "The request tried to create a checkout page, but one or more of the values in 'payment_method_type_categories' was set to null, an empty string or an unrecognized value. The request was rejected. Corrective action: Provide an array of strings that contain only the following values: 'bank_redirect', 'bank_transfer', 'card', 'cash', 'ewallet', 'rapyd_ewallet'" }, { "name": "ERROR_CHECKOUT_PAYMENT_METHOD_CATEGORY_CURRENCY_MISMATCH", "description": "The request tried to create a checkout page, but one of the payment method categories provided did not contain any payment methods that are supported in the country for the currency provided. The request was rejected. Corrective action: Remove the payment method category from the list." }, { "name": "ERROR_CHECKOUT_PAYMENT_METHOD_CURRENCY_MISMATCH", "description": "The request tried to create a checkout page, but the payment method was not recognized. The request was rejected. Corrective action: Specify a payment method that is valid for the country. Use 'List Payment Methods by Country'." }, { "name": "ERROR_CREATE_CHECKOUT_AMOUNT_OUT_OF_RANGE", "description": "The request tried to create a checkout page, but the amount was out of range for all payment methods available to you in the country, or for all payment methods that you specified. The request was rejected. Corrective action: For ‘amount’, specify an amount that is between the minimum and the maximum for at least one payment method. For details, run 'List Payment Methods by Country'." }, { "name": "ERROR_HOSTED_PAGE_AMOUNT_MISMATCH", "description": "The request tried to create a checkout page with a 'cart_items' object, but the value of the 'amount' parameter does not match the total amount of all items in the 'cart_items' object. The request was rejected. Corrective action: Specify the 'amount' parameter for each item in the cart, and omit it from the root of the request." }, { "name": "ERROR_HOSTED_PAGE_CONFLICTING_PAYMENT_METHOD_TYPES", "description": "The request tried to create a checkout page, but the request specified multiple ways of determining available payment methods. The request was rejected. Corrective action: Specify a 'payment_method_type', a list of types in 'payment_method_types_include', a list of types in 'payment_method_types_exclude' or a list of categories in 'payment_method_type_categories', or leave all of these parameters blank." }, { "name": "ERROR_HOSTED_PAGE_GET_CUSTOMER", "description": "The request tried to create a checkout page, but the customer was not found. The request was rejected. Corrective action: For 'customer', provide a valid customer ID, a string starting with 'cus_'." }, { "name": "ERROR_HOSTED_PAGE_INVALID_COUNTRY", "description": "The request tried to create a checkout page, but the country was not recognized. The request was rejected. Corrective action: For the 'country' field, use the 2-letter ISO 3166-1 ALPHA-2 code in uppercase letters." }, { "name": "ERROR_HOSTED_PAGE_INVALID_EXPORT_TYPE", "description": "The request tried to create a follow-up message after a payment via checkout page, but the 'type' parameter was not recognized. The request was rejected. Corrective action: Set 'type' to 'email' or 'text'." }, { "name": "ERROR_HOSTED_PAGE_INVALID_PAYMENT_METHOD_TYPE", "description": "The request tried to create a checkout page, but the payment method was not recognized. The request was rejected. Corrective action: Specify a payment method that is valid for the country. Use 'List Payment Methods by Country'." }, { "name": "ERROR_HOSTED_PAGE_INVALID_PAYMENT_METHOD_TYPE_AND_PAYMENT_METHOD_TYPE_CATEGORIES", "description": "The request tried to create a checkout page, but the request specified both a payment method type and a set of payment method type categories. The request was rejected. Corrective action: Specify 'payment_method_type' or a set of types in 'payment_method_type_categories', or leave both parameters blank." }, { "name": "ERROR_HOSTED_PAGE_INVALID_PAYMENT_METHOD_TYPE_CATEGORIES", "description": "The request tried to create a checkout page, but one or more of the values in 'payment_method_type_categories' was set to null, an empty string or an unrecognized value. The request was rejected. Corrective action: Provide an array of strings that contain only the following values: 'bank_redirect', 'bank_transfer', 'card', 'cash', 'ewallet', 'rapyd_ewallet'" }, { "name": "ERROR_HOSTED_PAGE_INVALID_STATUS", "description": "The request tried to create a payment for a checkout page, but the checkout page was already paid. The request was rejected. Corrective action: Determine why there were multiple attempts to pay the same checkout page." }, { "name": "ERROR_HOSTED_PAGE_PAYMENT_METHOD_TYPE_CATEGORIES_NOT_ENABLED", "description": "The request tried to create a checkout page, but one or more of the payment method type categories was not enabled. The request was rejected. Corrective action: Use the Client Portal to enable the payment method type categories you want to appear in the checkout page." }, { "name": "ERROR_HOSTED_PAGE_UNREADABLE_PAYMENT_METHOD_TYPES_EXCLUDE_LIST", "description": "The request tried to create a checkout page with a list of payment method types to exclude, but the data was not recognized. The request was rejected. Corrective action: In 'payment_method_types_exclude', specify a list of strings, each of which is a payment method type." }, { "name": "ERROR_HOSTED_PAGE_UNREADABLE_PAYMENT_METHOD_TYPES_INCLUDE_LIST", "description": "The request tried to create a checkout page with a list of payment method types to include, but the data was not recognized. The request was rejected. Corrective action: In 'payment_method_types_include', specify a list of strings, each of which is a payment method type." }, { "name": "ERROR_HOSTED_PAGE_UNRECOGNIZED_PAYMENT_METHOD_TYPE", "description": "The request tried to create a checkout page, but the payment method type specified is not available or does not exist at all. The request was rejected. Corrective action: Specify payment method types that are valid for the country. Use ‘List Payment Methods by Country’." }, { "name": "ERROR_HOSTED_PAGE_UNRECOGNIZED_PAYMENT_METHOD_TYPES_TO_INCLUDE", "description": "The request tried to create a hosted page, but the payout method types in 'payout_method_types_include' were not recognized. The request was rejected. Corrective action: Specify payout method types that are valid for the category, country and entity type. Use 'List Payout Method Types'." } ] }, { "product": "collect", "id": "custom-elements-object", "type": "type", "name": "CustomElements", "description": "The Custom Elements object contains the following fields:", "fields": [ { "name": "billing_address_collect", "type": [ { "type": "boolean" } ], "description": "Determines whether the customer is asked to fill in the billing address. Relevant when a card payment method is selected.\n\\* **true** - The address fields appear on the checkout page.\n\\* **false** - The address fields appear only if the `country` is **US**, **GB** or **CA**. This is the default.\n**Note:** When the customer already has address details, it will always be displayed.", "required": true }, { "name": "display_description", "type": [ { "type": "boolean" } ], "description": "Determines whether the checkout page displays the payment description.\n\\* **true** - The payment description appears.\n\\* **false** - The payment description does not appear. This is the default.\n\nRelevant when `description` is passed in the 'Create Checkout Page' request.", "required": true }, { "name": "dynamic_currency_conversion", "type": [ { "type": "boolean" } ], "description": "Determines whether the checkout page displays multiple currency options for a payment.\n\\* **true** - Multiple currency options appear.\n\\* **false** - Multiple currency options do not appear. This is the default.\n\nWhen the customer selects the requested currency, the checkout page displays the following information: \n\\* The original amount and currency. \n\\* The converted amount in the requested currency.\n\\* The exchange rate. \n\nRelevant when: \n\\* The 'Create Checkout Page' request passes `requested_currency`.\n\\* `fixed_side` is **buy**. \n\\* One or more payment methods support the values for `currency` and `requested_currency`.", "required": true }, { "name": "merchant_color", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "merchant_currency_only", "type": [ { "type": "boolean" } ], "description": "In a payment with FX where `fixed_side`=**buy**, determines whether the buyer's currency and the exchange rate appear. \nOne of the following:\n\\* **true** - The currency and the exchange rate are hidden.\n\\* **false** - The currency and the exchange rate appear. This is the default.", "required": true }, { "name": "payment_fees_display", "type": [ { "type": "boolean" } ], "description": "Determines whether payment fees appear on the checkout page. \n\\* **true** - Payment fees appear when the `payment_fees` object is set in the 'Create Checkout Page' request. This is the default.\n\\* **false** - Payment fees do not appear.", "required": true }, { "name": "save_card_default", "type": [ { "type": "boolean" } ], "description": "Determines whether the 'save card' checkbox is checked by default.\n\\* **true** - The 'save card' checkbox is checked.\n\\* **false** - The 'save card' checkbox is cleared. This is the default.\n\nRelevant when `customer_id` is passed in the 'Create Checkout Page' request.", "required": true } ] }, { "product": "issuing", "id": "virtual-account-number-object", "type": "type", "name": "VirtualAccountNumber", "description": "The Virtual Account Number object contains information about a bank account number added to a wallet. Money can be transferred to the virtual account number from any source and it appears in the wallet. A wallet can have many virtual account numbers. When money is added via the virtual account number, it appears in the wallet account for the currency of the transfer.", "fields": [ { "description": "ID of the Virtual Account Number object. String starting with **issuing_**.", "type": [ { "type": "string", "startsWith": "issuing_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount of the transaction, in units of the currency defined in `currency`. Decimal.", "required": true }, { "name": "bank_account", "type": [ { "type": "object" } ], "description": "Describes the type of bank account number, such as IBAN or ABA, and the actual bank account number.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "The two-letter ISO 3166-1 ALPHA-2 code for the country. Uppercase.\n\nTo determine the code for a country, see [List Countries](ref:list-countries).", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Currency for the virtual account number or the transaction. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the wallet.", "required": true }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the virtual account number is assigned to. String starting with **ewallet_**.", "required": true }, { "name": "issued_bank_account", "type": [ { "type": "string", "startsWith": "issuing_" } ], "description": "ID of the Virtual Account Number object. String starting with **issuing_**.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "ID of the virtual account, as provided by the merchant. Limited to 45 characters.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "status", "type": [ { "type": "string" } ], "description": "Indicates the status of the virtual account number object. \n* **ACT** - active.", "required": true }, { "name": "transactions", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "fields": [ { "name": "id", "type": [ { "type": "unknown" } ] }, { "name": "amount", "type": [ { "type": "unknown" } ] }, { "name": "currency", "type": [ { "type": "unknown" } ] }, { "name": "created_at", "type": [ { "type": "unknown" } ] } ] } ] } ], "description": "List of objects that describe individual transactions in the wallet that were done via the virtual account number. Each object has the following fields:\n* `id` - ID of the transaction. String starting with **isutran_**.\n* `amount` - Amount of the transaction, in units defined in `currency`.\n* `currency` - Currency of the transaction.\n* `created_at` - Timestamp for the transaction, in [*Unix time*](ref:glossary).", "required": true } ] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "issue-virtual-account-number-to-wallet", "type": "request", "name": "IssueVirtualAccountNumberToWalletRequest", "description": "Use the POST method to issue a virtual account number to an existing wallet. The virtual account number is for a single currency, but there is no limit to the number of virtual account numbers you can issue to a wallet. You can even issue multiple virtual account numbers in a single currency. These numbers can be used by any bank to transfer money to the wallet. When money is deposited to a virtual account number, it appears in the wallet account for the currency of that account.\n\n**Prerequisites**\n* You must create a wallet. See [Create Wallet](ref:create-wallet).\n* The identity of the wallet owner must be verified. For more information, see [Identity Verification Object](ref:identity-verification-object).", "method": "POST", "path": "/v1/issuing/bankaccounts", "params": [], "body": [ { "name": "country", "type": [ { "type": "string" } ], "required": true, "description": "The country that the account number will be associated with. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency of the account. Three-letter ISO 4217 code." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the account." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet the bank account number is issued to. String starting with **ewallet_**." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "ID of this account, as provided by the merchant. Limited to 45 characters." }, { "name": "metadata", "type": [ { "type": "string" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "simulate-a-bank-transfer-to-a-wallet", "type": "request", "name": "SimulateABankTransferToAWalletRequest", "description": "Use the POST method in the sandbox to simulate a deposit to a virtual account number that was issued to a wallet. This method is relevant only for testing in the sandbox.\n\n**Prerequisites:**\n* [Create Wallet](ref:create-wallet) \n* [Verify Identity](ref:verify-identity)\n* [Issue Virtual Account Number to Wallet](ref:issue-virtual-account-number-to-wallet)", "method": "POST", "path": "/v1/issuing/bankaccounts/bankaccounttransfertobankaccount", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the transaction, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency of the transaction. Three-letter ISO 4217 code." }, { "name": "issued_bank_account", "type": [ { "type": "string", "startsWith": "issuing_" } ], "required": true, "description": "ID of the Virtual Account Number object. String starting with **issuing_**." } ], "headers": [], "query": [] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "retrieve-virtual-account-history", "type": "request", "name": "RetrieveVirtualAccountHistoryRequest", "description": "Use the GET method to retrieve a Virtual Account Number object for a wallet. This object contains a list of all the transactions involving the virtual account number.", "method": "GET", "path": "/v1/issuing/bankaccounts/{issued_bank_account}", "params": [ { "name": "issued_bank_account", "type": [ { "type": "string", "startsWith": "issuing_" } ], "required": true, "description": "ID of the Virtual Account Number object. String starting with **issuing_**." } ], "body": [], "headers": [], "query": [] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "retrieve-virtual-account-transaction", "type": "request", "name": "RetrieveVirtualAccountTransactionRequest", "description": "Use the GET method to retrieve a virtual account transaction. To retrieve other wallet transactions, see [List Wallet Transactions](ref:list-wallet-transactions) and [Get Details of Wallet Transaction](ref:get-details-of-wallet-transaction).", "method": "GET", "path": "/v1/issuing/bankaccounts/{issued_bank_account}/transactions/{transaction}", "params": [ { "name": "issued_bank_account", "type": [ { "type": "string", "startsWith": "issuing_" } ], "required": true, "description": "ID of the Virtual Account Number object. String starting with **issuing_**." }, { "name": "transaction", "type": [ { "type": "string" } ], "required": true, "description": "ID of the transaction, as appears in the array of transactions in the response to 'Retrieve Bank Account History for Wallet'." } ], "body": [], "headers": [], "query": [] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "list-remitters-to-virtual-account-number", "type": "request", "name": "ListRemittersToVirtualAccountNumberRequest", "description": "Use the GET method to retrieve all remitters for the transfers to a virtual account number.", "method": "GET", "path": "/v1/issuing/bankaccounts/[issued_bank_account]/remitters", "params": [ { "name": "issued_bank_account", "type": [ { "type": "string", "startsWith": "issuing_" } ], "required": true, "description": "ID of the Virtual Account Number object. String starting with **issuing_**." } ], "body": [], "headers": [], "query": [] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "retrieve-remitter-details", "type": "request", "name": "RetrieveRemitterDetailsRequest", "description": "Use the GET method to retrieve the details of a remitter for a transfer to a virtual bank account.", "method": "GET", "path": "/v1/issuing/bankaccounts/remitters/[bankaccount]/transactions/[transaction]", "params": [ { "name": "issued_bank_account", "type": [ { "type": "string", "startsWith": "issuing_" } ], "required": true, "description": "ID of the Virtual Account Number object. String starting with **issuing_**." }, { "name": "transaction", "type": [ { "type": "string", "startsWith": "isutran_" } ], "required": true, "description": "ID of the transaction object. String starting with **isutran_**." } ], "body": [], "headers": [], "query": [] }, { "product": "issuing", "parent": "virtual-account-number-object", "id": "virtual-account-number-errors", "type": "enum", "name": "VirtualAccountNumberError", "values": [ { "name": "ERROR_GET_ISSUING", "description": "The request tried to retrieve a bank account object issued to a wallet, but the ID of the object was not recognized. The request was rejected. Corrective action: Provide the ID of a valid issued bank account object, a string starting with 'issuing_'." }, { "name": "ERROR_GET_ISSUING_TRANSACTION", "description": "The request tried to retrieve a bank account transaction for a wallet, but the transaction was not found. The request was rejected. Corrective action: For 'bank_account', use the bank account number that was issued to the wallet. For 'transaction', use the ID of the transaction, which is a UUID. To find the transaction ID, use 'Retrieve Bank Account History for Wallet'." }, { "name": "ERROR_ISSUING_BANK_ACCOUNT_COUNTRY_CURRENCY_MISMATCH", "description": "The request tried to issue a bank account number to a wallet, but the currency is not supported for the country provided. The request was rejected. Corrective action: Contact Client Support." }, { "name": "ERROR_ISSUING_DEPOSIT", "description": "The request tried to simulate a deposit to a bank account number that was issued to a wallet in the sandbox, but the bank account was not found. The request was rejected. Corrective action: For 'issued_bank_account', use the ID of a bank account number that was issued to a wallet. The ID is a string starting with 'issuing_'." }, { "name": "INVALID_EWALLET_TOKEN", "description": "The request tried to issue a bank account number to a wallet, but the wallet ID was missing from the request. The request was rejected. Corrective action: In the 'ewallet' field, provide the ID of a valid wallet, a string starting with 'ewallet_'." } ] }, { "product": "wallet", "id": "wallet-transaction-object", "type": "type", "name": "WalletTransaction", "description": "Transactions affecting the balances and limits of the accounts within the wallet.", "fields": [ { "description": "ID of the transaction. String starting with **wt_** or UUID.\n\nUnique identifier of the wallet object. String starting with **ewallet_**.\nRelevant to **Funds Added** and **Funds Removed** webhooks.", "type": [ { "type": "string", "startsWith": "wt_" } ], "name": "id", "required": true }, { "name": "accounts", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "wallet-object" } ] } ], "description": "Currency accounts of the wallet. See [Wallet Object](ref:wallet-object). \n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "name": "alias", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase.", "required": true }, { "name": "amount", "description": "**Transactions:** Amount of the transfer, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.\n\n**Wallet Account Operations:** Amount of the account limit. See [Wallet Limit Object](ref:wallet-limit-object).", "type": [ { "type": "number" } ], "required": true }, { "name": "balance", "type": [ { "type": "number" } ], "description": "The updated wallet balance after successful completion of the transaction.", "required": true }, { "name": "balance_type", "type": [ { "type": "string", "possibleValues": [ "available_balance", "on_hold_balance", "received_balance", "reserve_balance" ] } ], "description": "Balance type affected by the transaction. One of the following:\n\\* **available_balance**.\n\\* **on_hold_balance**.\n\\* **received_balance**.\n\\* **reserve_balance**.\nSee [Wallet Balance Types](ref:wallet-balance-types).", "required": true }, { "name": "category", "type": [ { "type": "string" } ], "description": "The type of client wallet. See [Wallet Object](ref:wallet-object).\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "name": "contacts", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "wallet-contact-object" } ] } ], "description": "Describes details about the wallet contacts. See [Wallet Contact Object](ref:wallet-contact-object).\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time the transaction was made, in [*Unix time*](ref:glossary).", "required": true }, { "name": "currency", "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Response only.", "required": true }, { "name": "destination_balance", "type": [ { "type": "string" } ], "description": "Indicates the destination balance type when funds are transferred from one balance to another within the wallet.", "required": true }, { "name": "destination_ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet receiving the money. String starting with **ewallet_**.", "required": true }, { "name": "destination_ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet receiving the money. String starting with **ewallet_**.", "required": true }, { "name": "destination_phone_number", "description": "Phone number of the owner of the wallet receiving the money, in E.164 format.", "type": [ { "type": "string" } ], "required": true }, { "name": "destination_transaction_id", "type": [ { "type": "string", "startsWith": "wt_" } ], "description": "ID of the transaction with regard to the destination. String starting with **wt_**.", "required": true }, { "name": "email", "type": [ { "type": "string" } ], "description": "Email address of the wallet owner.\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "name": "ending_before", "type": [ { "type": "string", "startsWith": "wt_" } ], "description": "The ID of the wallet transaction created after the last wallet transaction you want to retrieve. String starting with **wt_**.\n\nRelevant to [List Wallet Transactions](ref:list-wallet-transactions).", "required": true }, { "name": "ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet. String starting with **ewallet_**.", "required": true }, { "name": "ewallet_reference_id", "type": [ { "type": "string" } ], "description": "Optional wallet ID. See [Wallet Object](ref:wallet-object).\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "name": "first_name", "type": [ { "type": "string" } ], "description": "First name of the wallet owner. \n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "type": [ { "type": "string" } ], "description": "Family name of the wallet owner.\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "name": "last_name", "required": true }, { "name": "last_transaction_amount", "type": [ { "type": "number" } ], "description": "Amount of the Funds Added and Funds Removed transactions, in units of the currency defined in `last_transaction_currency`.\n\nResponse only.", "required": true }, { "name": "last_transaction_currency", "type": [ { "type": "number" } ], "description": "Three-letter ISO 4217 code for the currency used in the `last_transaction_amount` field.\n\nResponse only.", "required": true }, { "name": "limit", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "limits", "type": [ { "type": "string" } ], "description": "Includes details on limits for single and cumulative transactions.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "page_number", "type": [ { "type": "string" } ], "description": "Page number to retrieve. \n\nRelevant to [List Wallet Transactions](ref:list-wallet-transactions).", "required": true }, { "name": "page_size", "type": [ { "type": "string" } ], "description": "Number of results per page, up to 100. Default is **10**.\n\nRelevant to [List Wallet Transactions](ref:list-wallet-transactions).", "required": true }, { "description": "Phone number of the wallet owner in E.164 format.\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "name": "phone_number", "type": [ { "type": "string" } ], "required": true }, { "name": "reason", "type": [ { "type": "string" } ], "description": "Explanation for the action.", "required": true }, { "name": "response_metadata", "type": [ { "type": "object" } ], "description": "Metadata created with [Set Transfer Response](ref:set-transfer-response). Response only.", "required": true }, { "description": "Indicates the source balance type when funds are transferred from one balance to another within the wallet.", "type": [ { "type": "string" } ], "name": "source_balance", "required": true }, { "name": "source_ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet sending the money. String starting with **ewallet_**.", "required": true }, { "name": "source_ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet sending the money. String starting with **ewallet_**.", "required": true }, { "name": "source_phone_number", "description": "Phone number of the owner of the wallet sending the money, in E.164 format.", "type": [ { "type": "string" } ], "required": true }, { "name": "source_transaction_id", "type": [ { "type": "string", "startsWith": "wt_" } ], "description": "ID of the transaction with regard to the source. String starting with **wt_**.", "required": true }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "wt_" } ], "description": "The ID of the wallet transaction created before the first wallet transaction you want to retrieve. String starting with **wt_**.\n\nRelevant to [List Wallet Transactions](ref:list-wallet-transactions).", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "Response", "CAN", "CANCELED", "CLOSED" ] } ], "description": "**Funds Added and Funds Removed Webhooks:** Status of the wallet. See [Wallet Object](ref:wallet-object). Response only.\n\nStatus of the transaction.\n\n* **Webhook - Transfer Funds Between Wallets Response** and **Request (Set Transfer Response)** - One of the following:\n \\* **accept** - The transferee accepts the transfer.\n \\* **cancel** - The sender cancels the transaction.\n \\* **decline** - The transferee declines to accept the transfer.\n\n* **Response** - One of the following:\n\\* **CAN** - The sender canceled the transaction.\n \\* **DEC** - The transferee declined to accept the transfer.\n \\* **PEN** - Pending. Waiting for the transferee to respond.\n \\* **CLO** - Closed. The transferee accepted the transfer.\n\nOther transactions:\n\\* **CANCELED**\n\\* **CLOSED**", "required": true }, { "name": "timestamp", "type": [ { "type": "number" } ], "description": "Time of the webhook, in [*Unix time*](ref:glossary). Relevant to webhooks.", "required": true }, { "name": "transfer_response_at", "type": [ { "type": "number" } ], "description": "Time of the [Set Transfer Response](ref:set-transfer-response) operation, in [*Unix time*](ref:glossary). Read-only.", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "TransferRequest", "TransferCompleted" ] } ], "description": "**Funds Added and Funds Removed Webhooks:** Type of wallet. See [Wallet Object](ref:wallet-object).\n\n**Transactions:** Type of transaction. See [Transaction Types](ref:transaction-types).\n\n**Wallet Account Operations:** See [Wallet Limit Object](ref:wallet-limit-object).\n\n**Webhooks:** Type of webhook. One of the following:\n\\* **TransferRequest**\n\\* **TransferCompleted**", "required": true }, { "name": "verification_status", "type": [ { "type": "string" } ], "description": "Result of the verification check. See [Wallet Object](ref:wallet-object).\n\nRelevant to **Funds Added** and **Funds Removed** webhooks. Response only.", "required": true }, { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the Rapyd wallet. String starting with **ewallet_**. Relevant to wallet account transactions.", "required": true } ] }, { "product": "wallet", "id": "wallet-limit-object", "type": "type", "name": "WalletLimit", "description": "", "fields": [ { "name": "account_id", "type": [ { "type": "string" } ], "description": "The ID of the account within the wallet. UUID.", "required": true }, { "name": "amount", "type": [ { "type": "string" } ], "description": "The limit amount in the specified currency.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency of the amount.", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "min_balance_threshold", "max_balance_limit" ] } ], "description": "Type of limit. One of the following:\n\\* **min_balance_threshold** - The amount that triggers an email notification to increase the amount in the reserve balance.\n\\* **max_balance_limit** - The maximum balance that this account can hold.", "required": true }, { "name": "updated_at", "type": [ { "type": "string" } ], "description": "Timestamp for the request, in [*Unix time*](ref:glossary).", "required": true }, { "name": "wallet", "type": [ { "type": "string" } ], "description": "Rapyd Wallet ID defined by the customer or end user. Must be unique.", "required": true } ] }, { "product": "wallet", "id": "action-data-object", "type": "type", "name": "ActionData", "description": "The 'action_data' object in the response to [Get Details of Wallet Transaction](ref:get-details-of-wallet-transaction) contains details of the transaction. The fields of the object vary depending on the type of the transaction.", "fields": [ { "name": "address", "type": [ { "type": "object", "id": "address-object" } ], "description": "'address' object. For details, see [Address Object](ref:address-object).", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the transaction, in units defined in `currency`.", "required": true }, { "name": "captured", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment has been successfully captured. Read-only.", "required": true }, { "name": "client_type", "description": "Reserved.", "type": [ { "type": "string" } ], "required": true }, { "name": "complete_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected for final steps in completing the payment. Read-only.", "required": true }, { "name": "country_code", "type": [ { "type": "string" } ], "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the transaction object, in [*Unix time*](ref:glossary). Read-only.", "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "The transaction currency. In transactions with foreign exchange, this is the source currency.\nThree-letter ISO 4217 code for the currency. Uppercase.", "required": true }, { "name": "customer_token", "description": "ID of the customer who is making the payment. String starting with **cus_**. Required if `payment_method` is blank.\nFor more information, see [Customer Object](ref:customer-object).", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the transaction.", "required": true }, { "name": "dest_currency", "type": [ { "type": "string" } ], "description": "The destination currency in transactions with foreign exchange.\nThree-letter ISO 4217 code for the currency. Uppercase.", "required": true }, { "name": "dest_currency_symbol", "type": [ { "type": "string" } ], "description": "A URL link to the symbol of the destination currency .", "required": true }, { "name": "dispute", "type": [ { "type": "string" } ], "description": "Details about the dispute, if the transaction was disputed. Read-only.", "required": true }, { "name": "destination_city_id", "description": "Reserved.", "type": [ { "type": "string" } ], "required": true }, { "name": "destination_ewallet_id", "description": "ID of the wallet that the money is transferred to. String starting with **ewallet_**.", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true }, { "name": "error_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected in case of an error in the payment.", "required": true }, { "name": "escrow", "type": [ { "type": "string" } ], "description": "Determines whether the payment is held in escrow for later release. Relevant for card payments.\nRelevant to the request.", "required": true }, { "name": "ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is transferred from. String starting with **ewallet_**.", "required": true }, { "name": "ewallets", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "An array of one object, which contains the following fields:\n* **ewallet_id** - The ID of the wallet that the money is transferred from, a string starting with **ewallet_**.\n* **amount** - Amount of the transaction in currency units defined in `currency`.\n* **percent** - A decimal number representing a percentage of the total payout.\nRead-only.", "required": true }, { "name": "expiration", "type": [ { "type": "number" } ], "description": "Determines the time which the transaction must be completed by, in [*Unix time*](ref:glossary).", "required": true }, { "name": "expired_at", "type": [ { "type": "number" } ], "description": "Determines the time which the transaction must be completed by, in [*Unix time*](ref:glossary). Relevant to cash payouts.", "required": true }, { "name": "failure_code", "type": [ { "type": "string" } ], "description": "Error code explaining reason for failure of the transaction. Read-only.", "required": true }, { "name": "failure_message", "type": [ { "type": "string" } ], "description": "Message to the merchant, explaining the reason for failure of payment capture. Read-only.", "required": true }, { "name": "fixed_side", "type": [ { "type": "string" } ], "description": "Determines whether the FX rate is fixed for the buy side or for the sell side. Relevant for payment with FX.", "required": true }, { "name": "flow_type", "type": [ { "type": "string", "possibleValues": [ "redirect_url", "self_service_pos", "bank_transfer", "card", "ewallet" ] } ], "description": "Indicates the type of payment flow. Read-only. One of the following:\n* **redirect_url** - The customer is directed to a URL to complete the transaction.\n* **self_service_pos** - The customer completes the transaction at a point-of-sale location.\n* **bank_transfer** - The customer completes the transaction at the bank branch or bank website.\n* **card** - The transaction is completed immediately or on request of the merchant.\n* **ewallet** - The transaction is completed immediately or when funds are released from escrow.", "required": true }, { "name": "fx_rate", "type": [ { "type": "string" } ], "description": "Currency conversion rate for the transaction. Decimal. Read-only.", "required": true }, { "name": "group_payment", "type": [ { "type": "string" } ], "description": "ID of the group payment. Relevant when the payment is part of a group payment. Read-only.\nThe ID of the group payment, a string starting with 'gp_'.", "required": true }, { "name": "id", "type": [ { "type": "string" } ], "description": "ID of the transaction.", "required": true }, { "name": "instructions", "type": [ { "type": "object" } ], "description": "Describes how the customer makes the payment.\nContains the following fields:\n* **name** - Description of the payment method.\n* **steps** - A 'steps' object containing a list of steps for the customer to take. Each step is named step*N*, where *N* is an integer.\nRead-only.", "required": true }, { "name": "invoice", "type": [ { "type": "string", "startsWith": "inv_" } ], "description": "ID of the invoice that this payment is for. String starting with **inv_**. Read-only.", "required": true }, { "name": "is_group", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment is a group payment.", "required": true }, { "name": "is_partial", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment has been partially paid. When **false**, indicates that the payment is unpaid or fully paid. Read-only.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "Merchant-defined ID. Limited to 255 characters.", "required": true }, { "name": "merchant_requested_amount", "type": [ { "type": "number" } ], "description": "The amount of the payment in units of the currency paid by the sender, as defined in `merchant_requested_currency`. Relevant to payments with foreign exchange. Read only.", "required": true }, { "name": "merchant_requested_currency", "type": [ { "type": "string" } ], "description": "The currency that the payment is converted into. Corresponds to `currency` in the request. Three-letter ISO 4217 code. Uppercase. Relevant to payments with foreign exchange. Read only.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the Rapyd partner.", "required": true }, { "name": "order", "description": "ID of the order that this payment is for. Read-only. Relevant when the payment is for an order.", "type": [ { "type": "string" } ], "required": true }, { "name": "original_amount", "type": [ { "type": "number" } ], "description": "Value depends on the transaction type:\n* **Foreign exchange payments** - The amount paid by the sender, in units of the currency defined in `requested_currency`, including gross transaction fees and gross FX fees. \n\n* **Payments not involving foreign exchange** - The amount of the payment, in units of the currency defined in `currency`, including gross transaction fees.\nRead-only.", "required": true }, { "name": "outcome", "type": [ { "type": "object", "fields": [ { "name": "network_status", "type": [ { "type": "unknown" } ] }, { "name": "risk_level", "type": [ { "type": "unknown" } ] }, { "name": "seller_message", "type": [ { "type": "unknown" } ] }, { "name": "type", "type": [ { "type": "unknown" } ] }, { "name": "reason", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contains the following fields:\n* `network_status` - Network status of the payment. One of the following: \n * **approved_by_network**\n * **declined_by_network**\n * **not_sent_to_network**\n * **reversed_after_approval**\n* `risk_level` - Assessment of the risk level of the payment.One of the following: \n * **normal**\n * **elevated**\n * **highest**\n * **not_assessed**\n* `seller_message` - Message to the merchant.\n* `type` - One of the following:\n * **authorized**\n * **manual_review**\n * **issuer_declined**\n * **blocked**\n * **invalid**\n* `reason` - More detailed indication of the reason indicated by `type`. One of the following:\n * **highest_risk_level** - Blocked by default rules.\n * **elevated_risk_level** - Placed in review by default rules.\n * **rule** - Placed in review by rules defined by the client. Read-only.", "required": true }, { "name": "paid", "description": "Indicates whether the payment has been fully collected. Read-only.", "type": [ { "type": "boolean" } ], "required": true }, { "name": "paid_at", "type": [ { "type": "number" } ], "description": "Time of the transaction, in [*Unix time*](ref:glossary). Read-only.", "required": true }, { "name": "payment_fees", "description": "Defines transaction fees and foreign exchange fees.", "type": [ { "type": "object" } ], "required": true }, { "name": "payment_method", "type": [ { "type": "string" }, { "type": "object" } ], "description": "'payment_method' object or ID. If not specified in this field, the payment method is the default payment method specified for the customer.\n\nThe 'payment_method' object contains a `type` field and a `fields` object. For more information, see [Payment Method Object](#payment-method-object).", "required": true }, { "name": "payment_method_options", "type": [ { "type": "object" } ], "description": "Object describing additional information required for the payment. To determine the fields required, run [Get Payment Method Required Fields](ref:get-payment-method-required-fields).", "required": true }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "description": "The type of transaction method, payment or payout type.\nUse [List Payout Method Types](ref:list-payout-method-types) or [List Payment Method Types](ref:list-payment-method-types) for a list of supported types for a country.", "required": true }, { "name": "payment_method_type_category", "type": [ { "type": "string", "possibleValues": [ "bank_transfer", "bank_redirect", "card", "cash" ] } ], "description": "Category of payment method type. Read-only. One of the following: \n* **bank_transfer** \n* **bank_redirect** \n* **card** \n* **cash**", "required": true }, { "name": "phone_number", "type": [ { "type": "string" } ], "description": "The customer's primary phone number in E.164 format. The merchant is responsible for verifying that the number is correct. One method of verifying might be to send an activation code to the phone by SMS, with a limited time for response.", "required": true }, { "name": "price_before_changes", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "proportional_refund", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment is a group payment and refund is made in proportion between group payers.", "required": true }, { "name": "quote_id", "description": "ID of the currency exchange quote.", "type": [ { "type": "string" } ], "required": true }, { "name": "quotes_comparisons", "type": [ { "type": "object" } ], "description": "Reserved.", "required": true }, { "name": "reason", "type": [ { "type": "string" } ], "description": "Reason for issuing the transaction. Free text.", "required": true }, { "name": "receipt_email", "type": [ { "type": "string" } ], "description": "Email address that the receipt for this transaction is sent to.", "required": true }, { "name": "receipt_number", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "redirect_url", "type": [ { "type": "string" } ], "description": "URL where the customer can complete a payment. Relevant when `payment_flow_type` is **redirect**. Read-only.", "required": true }, { "name": "refunded", "type": [ { "type": "boolean" } ], "description": "Indicates whether there was a refund against this payment. Read-only.", "required": true }, { "name": "refunded_amount", "type": [ { "type": "number" } ], "description": "The total amount refunded against this payment, in units of the currency defined in `currency`. Read-only.", "required": true }, { "name": "refunds", "description": "An object containing the following fields:\n* `data` - A list of up to three refunds.\n* `has_more` - Indicates whether there are more than three refunds against this payment.\n* `total_count` - Total number of refunds against this payment.\n* `url` - URL for requesting all of the refunds against this payment.\nRead-only.", "type": [ { "type": "object", "fields": [ { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ] } ], "required": true }, { "name": "rewards", "type": [ { "type": "object" } ], "description": "Reserved.", "required": true }, { "name": "source_wallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is transferred from. String starting with **ewallet_**.", "required": true }, { "name": "src_currency", "description": "The source currency in transactions with foreign exchange.\nThree-letter ISO 4217 code for the currency. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "src_currency_symbol", "type": [ { "type": "string" } ], "description": "A URL link to the source-currency symbol.", "required": true }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "description": "A text description suitable for a customer's payment statement. Limited to 22 characters.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "CANCELED", "CLOSED" ] } ], "description": "Status of the transaction. One of the following:\n* **CANCELED**\n* **CLOSED**", "required": true }, { "name": "textual_codes", "type": [ { "type": "object", "fields": [ { "name": "code", "type": [ { "type": "unknown" } ] }, { "name": "pay_code", "type": [ { "type": "unknown" } ] }, { "name": "pairing_code", "type": [ { "type": "unknown" } ] }, { "name": "payment_code", "type": [ { "type": "unknown" } ] }, { "name": "response_code", "type": [ { "type": "unknown" } ] } ] } ], "description": "A set of text codes for the customer to use to complete the steps described in the `instructions` field.\nContains one or more of the following fields:\n* `code`\n* `pay_code` \n* `pairing_code` \n* `payment_code` \n* `response_code`\nRead-only.", "required": true }, { "name": "transaction_id", "type": [ { "type": "string" } ], "description": "ID of the associated transaction. Read-only.", "required": true }, { "description": "Type of transaction. See [Transaction Types](ref:transaction-types).", "type": [ { "type": "string" } ], "name": "type", "required": true }, { "name": "visual_codes", "type": [ { "type": "object" } ], "description": "A set of images for the customer to use to complete the steps described in the `instructions` field. For example, a QR code or barcode. Read-only.", "required": true } ] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "transfer-funds-between-wallets", "type": "request", "name": "TransferFundsBetweenWalletsRequest", "description": "Use the POST method to transfer funds between Rapyd Wallets. If the destination wallet does not have an account for the specified currency, the account is created. If the source wallet does not have enough funds in the account for the specified currency, the transfer fails.\n\nThe status of the transfer is **PEN** while the transfer is pending and the transferee has not accepted the transfer. If the transferee fails to respond to the transfer request, the sender must cancel the transaction with [Set Transfer Response](ref:set-transfer-response), with `status` set to **cancel**.\n\nThis method triggers the **Webhook - Transfer Funds Between Wallets Created**. See [Webhook - Transfer Funds Between Wallets Created](ref:webhook-transfer-funds-between-wallets-created).", "method": "POST", "path": "/v1/account/transfer", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "Amount of the transfer. Decimal." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase." }, { "name": "destination_ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet receiving the money. String starting with **ewallet_**." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "source_ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet sending the money. String starting with **ewallet_**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "set-transfer-response", "type": "request", "name": "SetTransferResponseRequest", "description": "Use the POST method to respond to a funds transfer between wallets. The transferee uses this method to accept or decline the transfer. If the transferee fails to respond to the transfer, the sender must use this method to cancel the transfer.\n\nThis method triggers the **Webhook - Transfer Funds Between Wallets Response**. See [Webhook - Transfer Funds Between Wallets Response](ref:webhook-transfer-funds-between-wallets-response).\n\n**NOTE:** This method can be used only one time per transfer transaction.", "method": "POST", "path": "/v1/account/transfer/response", "params": [], "body": [ { "name": "id", "type": [ { "type": "string" } ], "required": true, "description": "ID of the transfer transaction, from the 'id' field in the 'data' object of the response. 32-digit hexadecimal." }, { "name": "status", "type": [ { "type": "string" } ], "required": true, "description": "Determines how to handle the transfer. One of the following values: **accept**, **decline**, **cancel**" }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "put-funds-on-hold", "type": "request", "name": "PutFundsOnHoldRequest", "description": "Use the POST method to put a hold on funds in the wallet. This action transfers funds from the available balance to the on-hold balance. If the wallet does not have enough funds in the available balance in the specified currency, the transfer fails.\n\nThis method triggers the **Transfer Funds Between Balances** webhook. This webhook contains the same information as the response.\n\nThe customer cannot move funds that are on hold until the client releases the hold.\n\nThis method is relevant for person and company wallets.", "method": "POST", "path": "/v1/account/balance/hold", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "Amount of the transfer. Decimal." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet associated with the contact. String starting with **ewallet_**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "release-on-hold-funds", "type": "request", "name": "ReleaseOnHoldFundsRequest", "description": "Use the POST method to release a hold on funds in the wallet. This action transfers funds from the on-hold balance to the available balance. If the wallet does not have enough funds in the on-hold balance in the specified currency, the transfer fails.\n\nThis method triggers the **Transfer Funds Between Balances** webhook. This webhook contains the same information as the response.\n\nThis method is relevant for person and company wallets.", "method": "POST", "path": "/v1/account/balance/release", "params": [], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "Amount of the transfer. Decimal." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Three-letter ISO 4217 code for the currency used in the `amount` field. Uppercase." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet associated with the contact. String starting with **ewallet_**." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "set-wallet-account-limit", "type": "request", "name": "SetWalletAccountLimitRequest", "description": "Use the POST method to set the maximum balance limit or the minimum balance threshold for an existing wallet account.\n\n**Note:** The request must specify the `account_id` or the `currency`.", "method": "POST", "path": "/v1/user/{wallet}/account/limits", "params": [ { "name": "wallet", "type": [ { "type": "string" } ], "required": true, "description": "Rapyd Wallet ID." } ], "body": [ { "name": "account_id", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the account within the wallet." }, { "name": "amount", "type": [ { "type": "string" } ], "required": true, "description": "The amount of the limit." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency of an existing account." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "The limit type." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "delete-wallet-account-limit", "type": "request", "name": "DeleteWalletAccountLimitRequest", "description": "Use the DELETE method to delete a limit on a wallet account.\n\n**Note:** The request must specify the `account_id` or the `currency`.", "method": "DELETE", "path": "/v1/user/{wallet}/account/limits", "params": [ { "name": "wallet", "type": [ { "type": "string" } ], "required": true, "description": "Rapyd Wallet ID defined by the customer or end user. Must be unique." } ], "body": [ { "name": "account_id", "type": [ { "type": "string" } ], "required": false, "description": "The ID of the account within the wallet." }, { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency of the amount." }, { "name": "type", "type": [ { "type": "string" } ], "required": true, "description": "The limit type." } ], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "list-wallet-transactions", "type": "request", "name": "ListWalletTransactionsRequest", "description": "Use the GET method to retrieve a list of all transactions related to a wallet.", "method": "GET", "path": "/v1/user/{wallet}/transactions", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet. String starting with **ewallet_**." } ], "body": [], "headers": [], "query": [ { "name": "currency", "type": [ { "type": "string" } ], "required": false, "description": "Three-letter ISO 4217 code for the currency of the transactions. Uppercase." }, { "name": "end_date", "type": [ { "type": "number" } ], "required": false, "description": "Timestamp of the last transaction or later, in [*Unix time*](ref:glossary)." }, { "name": "ending_before", "type": [ { "type": "string", "startsWith": "wt_" } ], "required": false, "description": "The ID of the wallet transaction created after the last wallet transaction you want to retrieve. String starting with **wt_**." }, { "name": "page_number", "type": [ { "type": "string" } ], "required": false, "description": "Page number to retrieve." }, { "name": "page_size", "type": [ { "type": "string" } ], "required": false, "description": "Number of results per page." }, { "name": "start_date", "type": [ { "type": "number" } ], "required": false, "description": "Timestamp of the first transaction or earlier, in [*Unix time*](ref:glossary)." }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "wt_" } ], "required": false, "description": "The ID of the wallet transaction created before the first wallet transaction you want to retrieve. String starting with **wt_**." }, { "name": "type", "type": [ { "type": "string" } ], "required": false, "description": "Type of transaction." } ] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "retrieve-wallet-balances", "type": "request", "name": "RetrieveWalletBalancesRequest", "description": "Use the GET method to retrieve details of the balances in a Rapyd Wallet.", "method": "GET", "path": "/v1/user/{wallet}/accounts", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the Rapyd Wallet. String starting with **ewallet_**" } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "get-details-of-wallet-transaction", "type": "request", "name": "GetDetailsOfWalletTransactionRequest", "description": "Use the GET method to retrieve the details of a wallet transaction.", "method": "GET", "path": "/v1/user/{wallet}/transactions/{transaction}", "params": [ { "name": "wallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true, "description": "ID of the wallet. String starting with **ewallet_**." }, { "name": "transaction", "type": [ { "type": "string", "startsWith": "wt_" } ], "required": true, "description": "ID of the transaction, from the response to [List Wallet Transactions](ref:list-wallet-transactions). String starting with **wt_**." } ], "body": [], "headers": [], "query": [] }, { "product": "wallet", "parent": "wallet-transaction-object", "id": "wallet-transaction-errors", "type": "enum", "name": "WalletTransactionError", "values": [ { "name": "CANCEL_TRANSACTION_ERROR", "description": "The request tried to cancel a wallet transaction, but the transaction was not found. The request was rejected. Corrective action: Provide a valid transaction ID." }, { "name": "COMPLETE_TRANSACTION_ERROR", "description": "The request tried to complete a wallet transaction, but the transaction was not found. The request was rejected. Corrective action: Provide a valid transaction ID." }, { "name": "ERROR_AMOUNT_EXCEEDS_DESTINATION_EWALLET_LIMIT", "description": "The request attempted an operation that puts funds in a wallet, but the amount exceeds the limit set for that wallet for funds of that currency. The request was rejected. Corrective action: Transfer an amount that does not put the destination wallet over its limit for that currency." }, { "name": "ERROR_AMOUNT_EXCEEDS_DESTINATION_EWALLET_LIMIT_BY_MERCHANT_CONTROLLED_PARAMETERS", "description": "The request tried to transfer funds to a wallet, but the amount would cause the wallet to exceed its balance limit. The request was rejected. Corrective action: Remove money from the wallet before trying to add more, or deposit a different amount. To raise the balance limit, you can complete the customer identity verification process." }, { "name": "ERROR_EWALLET_ACCOUNT_LIMIT_EXCEEDS_CURRENT_BALANCE", "description": "The request tried to create or update a limit on a wallet currency account, but the limit offered was lower than the amount of currency in the account. The request was rejected. Corrective action: Set a limit that is less than or equal to the amount currently in the account." }, { "name": "ERROR_EWALLET_LIMIT_NOT_VALID", "description": "The request tried to create or update a limit on a wallet currency account, but the limit was not valid. The request was rejected. Corrective action: Use a positive number." }, { "name": "ERROR_EWALLET_TRANSFER_DESTINATION_EWALLET_DISABLED", "description": "The request tried to transfer funds to a wallet, but the wallet was disabled. The request was rejected. Corrective action: Enable the destination wallet." }, { "name": "ERROR_EWALLET_TRANSFER_ID_NOT_FOUND", "description": "The request tried to set a response to a transfer between wallets, but the ID of the transfer transaction was not found. The request was rejected. Corrective action: Use a valid transaction ID." }, { "name": "ERROR_EWALLET_TRANSFER_SOURCE_EWALLET_DISABLED", "description": "The request tried to transfer funds from a wallet, but the wallet was disabled. The request was rejected. Corrective action: Enable the source wallet." }, { "name": "ERROR_EWALLET_TRANSFER_SOURCE_EWALLET_NOT_FOUND", "description": "The request tried to transfer funds from a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the correct phone number for the source wallet." }, { "name": "ERROR_GET_ACCOUNT_FUNDS_DETAILS", "description": "The request tried to retrieve details of a transaction, but the transaction was not found. The request was rejected. Corrective action: Provide a valid transaction ID, which is a UUID." }, { "name": "ERROR_GET_ISSUING_TRANSACTION", "description": "The request tried to retrieve a bank account transaction for a wallet, but the transaction was not found. The request was rejected. Corrective action: For 'bank_account', use the bank account number that was issued to the wallet. For 'transaction', use the ID of the transaction, which is a UUID. To find the transaction ID, use 'Retrieve Bank Account History for Wallet'." }, { "name": "ERROR_GET_TRANSACTION", "description": "The request tried to retrieve a transaction, but the transaction was not found. The request was rejected. Corrective action: Use the ID of a wallet that has not been closed, and the ID of a transaction that is associated with that wallet." }, { "name": "ERROR_PUT_FUNDS_ON_HOLD_CLIENT_WALLET", "description": "The request attempted to put funds on hold, but this operation is not permitted for a client wallet. The request was rejected. Corrective action. None." }, { "name": "ERROR_RELEASE_ON_HOLD_FUNDS_CLIENT_WALLET", "description": "The request attempted to release on-hold funds, but this operation is not permitted for a client wallet. The request was rejected. Corrective action. None." }, { "name": "ERROR_RESPONSE_TRANSFER", "description": "The request tried to accept, reject or cancel a transfer that was previously declined by the transferee. The request was rejected. Corrective action: If the intent was to accept, create a new transfer. Otherwise, determine why a transfer response was attempted on a declined transaction." }, { "name": "ERROR_TRANSFER_FUNDS_DESTINATION_AND_SOURCE_CANNOT_BE_THE_SAME", "description": "The request tried to transfer funds, but the source was the same as the destination. The request was rejected. Corrective action: Set 'source_ewallet' and 'destination_ewallet' to the IDs of two different wallets." }, { "name": "ERROR_TRANSFER_RESPONSE_INVALID_DETAILS", "description": "The request tried to accept, reject or cancel a transfer between wallets, but the transaction was not found. The request was rejected. Corrective action: If the intent was to accept, create a new transfer." }, { "name": "ERROR_TRANSFER_RESPONSE_PREVIOUSLY_CANCELED", "description": "The request tried to accept, reject or cancel a transfer that was previously canceled by the sender. The request was rejected. Corrective action: If the intent was to accept, create a new transfer. Otherwise, determine why a transfer response was attempted on a canceled transaction." }, { "name": "ERROR_TRANSFER_RESPONSE_PREVIOUSLY_DECLINED", "description": "The request tried to accept, reject or cancel a transfer that was previously declined by the transferee. The request was rejected. Corrective action: If the intent was to accept, create a new transfer. Otherwise, determine why a transfer response was attempted on a declined transaction." }, { "name": "ERROR_UPDATE_FUNDS", "description": "The request tried to add funds to or remove funds from a wallet, but the wallet was not found. The request was rejected. Corrective action: Set 'ewallet' to the ID of a valid wallet that has not been blocked or deleted. The ID is a string starting with 'ewallet_'." }, { "name": "INVALID_TRANSACTION_ID", "description": "The request tried to retrieve a transaction, but the transaction was not found. The request was rejected. Corrective action: Verify that the transaction ID is correct and that it is associated with the eWallet specified." }, { "name": "INVALID_TRANSFER_DETAILS", "description": "The request tried to transfer funds from a wallet to another wallet, but the input parameters were not valid. The request was rejected. Corrective action: For 'currency', use the ISO 4217 code. For 'source_ewallet' and 'destination_ewallet', use the IDs of valid wallets." }, { "name": "INVALID_TRANSFER_STATUS", "description": "The request tried to set a response to a transfer between eWallets, but the status was not recognized. The request was rejected. Corrective action: Set the 'status' field to one of the following values: 'accept', 'decline', 'cancel'." }, { "name": "NOT_ENOUGH_FUNDS", "description": "The request attempted an operation that requires funds in a specific currency, but there were not sufficient funds in that currency. The request was rejected. Corrective action: Transfer funds to the wallet in the required currency." } ] }, { "product": "wallet", "id": "wallet-limit-object", "type": "type", "name": "WalletLimit", "description": "", "fields": [ { "name": "account_id", "type": [ { "type": "string" } ], "description": "The ID of the account within the wallet. UUID.", "required": true }, { "name": "amount", "type": [ { "type": "string" } ], "description": "The limit amount in the specified currency.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Three-letter ISO 4217 code for the currency of the amount.", "required": true }, { "name": "type", "type": [ { "type": "string", "possibleValues": [ "min_balance_threshold", "max_balance_limit" ] } ], "description": "Type of limit. One of the following:\n\\* **min_balance_threshold** - The amount that triggers an email notification to increase the amount in the reserve balance.\n\\* **max_balance_limit** - The maximum balance that this account can hold.", "required": true }, { "name": "updated_at", "type": [ { "type": "string" } ], "description": "Timestamp for the request, in [*Unix time*](ref:glossary).", "required": true }, { "name": "wallet", "type": [ { "type": "string" } ], "description": "Rapyd Wallet ID defined by the customer or end user. Must be unique.", "required": true } ] }, { "product": "wallet", "id": "action-data-object", "type": "type", "name": "ActionData", "description": "The 'action_data' object in the response to [Get Details of Wallet Transaction](ref:get-details-of-wallet-transaction) contains details of the transaction. The fields of the object vary depending on the type of the transaction.", "fields": [ { "name": "address", "type": [ { "type": "object", "id": "address-object" } ], "description": "'address' object. For details, see [Address Object](ref:address-object).", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the transaction, in units defined in `currency`.", "required": true }, { "name": "captured", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment has been successfully captured. Read-only.", "required": true }, { "name": "client_type", "description": "Reserved.", "type": [ { "type": "string" } ], "required": true }, { "name": "complete_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected for final steps in completing the payment. Read-only.", "required": true }, { "name": "country_code", "type": [ { "type": "string" } ], "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the transaction object, in [*Unix time*](ref:glossary). Read-only.", "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "The transaction currency. In transactions with foreign exchange, this is the source currency.\nThree-letter ISO 4217 code for the currency. Uppercase.", "required": true }, { "name": "customer_token", "description": "ID of the customer who is making the payment. String starting with **cus_**. Required if `payment_method` is blank.\nFor more information, see [Customer Object](ref:customer-object).", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the transaction.", "required": true }, { "name": "dest_currency", "type": [ { "type": "string" } ], "description": "The destination currency in transactions with foreign exchange.\nThree-letter ISO 4217 code for the currency. Uppercase.", "required": true }, { "name": "dest_currency_symbol", "type": [ { "type": "string" } ], "description": "A URL link to the symbol of the destination currency .", "required": true }, { "name": "dispute", "type": [ { "type": "string" } ], "description": "Details about the dispute, if the transaction was disputed. Read-only.", "required": true }, { "name": "destination_city_id", "description": "Reserved.", "type": [ { "type": "string" } ], "required": true }, { "name": "destination_ewallet_id", "description": "ID of the wallet that the money is transferred to. String starting with **ewallet_**.", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": true }, { "name": "error_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected in case of an error in the payment.", "required": true }, { "name": "escrow", "type": [ { "type": "string" } ], "description": "Determines whether the payment is held in escrow for later release. Relevant for card payments.\nRelevant to the request.", "required": true }, { "name": "ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is transferred from. String starting with **ewallet_**.", "required": true }, { "name": "ewallets", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "An array of one object, which contains the following fields:\n* **ewallet_id** - The ID of the wallet that the money is transferred from, a string starting with **ewallet_**.\n* **amount** - Amount of the transaction in currency units defined in `currency`.\n* **percent** - A decimal number representing a percentage of the total payout.\nRead-only.", "required": true }, { "name": "expiration", "type": [ { "type": "number" } ], "description": "Determines the time which the transaction must be completed by, in [*Unix time*](ref:glossary).", "required": true }, { "name": "expired_at", "type": [ { "type": "number" } ], "description": "Determines the time which the transaction must be completed by, in [*Unix time*](ref:glossary). Relevant to cash payouts.", "required": true }, { "name": "failure_code", "type": [ { "type": "string" } ], "description": "Error code explaining reason for failure of the transaction. Read-only.", "required": true }, { "name": "failure_message", "type": [ { "type": "string" } ], "description": "Message to the merchant, explaining the reason for failure of payment capture. Read-only.", "required": true }, { "name": "fixed_side", "type": [ { "type": "string" } ], "description": "Determines whether the FX rate is fixed for the buy side or for the sell side. Relevant for payment with FX.", "required": true }, { "name": "flow_type", "type": [ { "type": "string", "possibleValues": [ "redirect_url", "self_service_pos", "bank_transfer", "card", "ewallet" ] } ], "description": "Indicates the type of payment flow. Read-only. One of the following:\n* **redirect_url** - The customer is directed to a URL to complete the transaction.\n* **self_service_pos** - The customer completes the transaction at a point-of-sale location.\n* **bank_transfer** - The customer completes the transaction at the bank branch or bank website.\n* **card** - The transaction is completed immediately or on request of the merchant.\n* **ewallet** - The transaction is completed immediately or when funds are released from escrow.", "required": true }, { "name": "fx_rate", "type": [ { "type": "string" } ], "description": "Currency conversion rate for the transaction. Decimal. Read-only.", "required": true }, { "name": "group_payment", "type": [ { "type": "string" } ], "description": "ID of the group payment. Relevant when the payment is part of a group payment. Read-only.\nThe ID of the group payment, a string starting with 'gp_'.", "required": true }, { "name": "id", "type": [ { "type": "string" } ], "description": "ID of the transaction.", "required": true }, { "name": "instructions", "type": [ { "type": "object" } ], "description": "Describes how the customer makes the payment.\nContains the following fields:\n* **name** - Description of the payment method.\n* **steps** - A 'steps' object containing a list of steps for the customer to take. Each step is named step*N*, where *N* is an integer.\nRead-only.", "required": true }, { "name": "invoice", "type": [ { "type": "string", "startsWith": "inv_" } ], "description": "ID of the invoice that this payment is for. String starting with **inv_**. Read-only.", "required": true }, { "name": "is_group", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment is a group payment.", "required": true }, { "name": "is_partial", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment has been partially paid. When **false**, indicates that the payment is unpaid or fully paid. Read-only.", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "Merchant-defined ID. Limited to 255 characters.", "required": true }, { "name": "merchant_requested_amount", "type": [ { "type": "number" } ], "description": "The amount of the payment in units of the currency paid by the sender, as defined in `merchant_requested_currency`. Relevant to payments with foreign exchange. Read only.", "required": true }, { "name": "merchant_requested_currency", "type": [ { "type": "string" } ], "description": "The currency that the payment is converted into. Corresponds to `currency` in the request. Three-letter ISO 4217 code. Uppercase. Relevant to payments with foreign exchange. Read only.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the Rapyd partner.", "required": true }, { "name": "order", "description": "ID of the order that this payment is for. Read-only. Relevant when the payment is for an order.", "type": [ { "type": "string" } ], "required": true }, { "name": "original_amount", "type": [ { "type": "number" } ], "description": "Value depends on the transaction type:\n* **Foreign exchange payments** - The amount paid by the sender, in units of the currency defined in `requested_currency`, including gross transaction fees and gross FX fees. \n\n* **Payments not involving foreign exchange** - The amount of the payment, in units of the currency defined in `currency`, including gross transaction fees.\nRead-only.", "required": true }, { "name": "outcome", "type": [ { "type": "object", "fields": [ { "name": "network_status", "type": [ { "type": "unknown" } ] }, { "name": "risk_level", "type": [ { "type": "unknown" } ] }, { "name": "seller_message", "type": [ { "type": "unknown" } ] }, { "name": "type", "type": [ { "type": "unknown" } ] }, { "name": "reason", "type": [ { "type": "unknown" } ] } ] } ], "description": "Contains the following fields:\n* `network_status` - Network status of the payment. One of the following: \n * **approved_by_network**\n * **declined_by_network**\n * **not_sent_to_network**\n * **reversed_after_approval**\n* `risk_level` - Assessment of the risk level of the payment.One of the following: \n * **normal**\n * **elevated**\n * **highest**\n * **not_assessed**\n* `seller_message` - Message to the merchant.\n* `type` - One of the following:\n * **authorized**\n * **manual_review**\n * **issuer_declined**\n * **blocked**\n * **invalid**\n* `reason` - More detailed indication of the reason indicated by `type`. One of the following:\n * **highest_risk_level** - Blocked by default rules.\n * **elevated_risk_level** - Placed in review by default rules.\n * **rule** - Placed in review by rules defined by the client. Read-only.", "required": true }, { "name": "paid", "description": "Indicates whether the payment has been fully collected. Read-only.", "type": [ { "type": "boolean" } ], "required": true }, { "name": "paid_at", "type": [ { "type": "number" } ], "description": "Time of the transaction, in [*Unix time*](ref:glossary). Read-only.", "required": true }, { "name": "payment_fees", "description": "Defines transaction fees and foreign exchange fees.", "type": [ { "type": "object" } ], "required": true }, { "name": "payment_method", "type": [ { "type": "string" }, { "type": "object" } ], "description": "'payment_method' object or ID. If not specified in this field, the payment method is the default payment method specified for the customer.\n\nThe 'payment_method' object contains a `type` field and a `fields` object. For more information, see [Payment Method Object](#payment-method-object).", "required": true }, { "name": "payment_method_options", "type": [ { "type": "object" } ], "description": "Object describing additional information required for the payment. To determine the fields required, run [Get Payment Method Required Fields](ref:get-payment-method-required-fields).", "required": true }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "description": "The type of transaction method, payment or payout type.\nUse [List Payout Method Types](ref:list-payout-method-types) or [List Payment Method Types](ref:list-payment-method-types) for a list of supported types for a country.", "required": true }, { "name": "payment_method_type_category", "type": [ { "type": "string", "possibleValues": [ "bank_transfer", "bank_redirect", "card", "cash" ] } ], "description": "Category of payment method type. Read-only. One of the following: \n* **bank_transfer** \n* **bank_redirect** \n* **card** \n* **cash**", "required": true }, { "name": "phone_number", "type": [ { "type": "string" } ], "description": "The customer's primary phone number in E.164 format. The merchant is responsible for verifying that the number is correct. One method of verifying might be to send an activation code to the phone by SMS, with a limited time for response.", "required": true }, { "name": "price_before_changes", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "proportional_refund", "type": [ { "type": "boolean" } ], "description": "Indicates that the payment is a group payment and refund is made in proportion between group payers.", "required": true }, { "name": "quote_id", "description": "ID of the currency exchange quote.", "type": [ { "type": "string" } ], "required": true }, { "name": "quotes_comparisons", "type": [ { "type": "object" } ], "description": "Reserved.", "required": true }, { "name": "reason", "type": [ { "type": "string" } ], "description": "Reason for issuing the transaction. Free text.", "required": true }, { "name": "receipt_email", "type": [ { "type": "string" } ], "description": "Email address that the receipt for this transaction is sent to.", "required": true }, { "name": "receipt_number", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "redirect_url", "type": [ { "type": "string" } ], "description": "URL where the customer can complete a payment. Relevant when `payment_flow_type` is **redirect**. Read-only.", "required": true }, { "name": "refunded", "type": [ { "type": "boolean" } ], "description": "Indicates whether there was a refund against this payment. Read-only.", "required": true }, { "name": "refunded_amount", "type": [ { "type": "number" } ], "description": "The total amount refunded against this payment, in units of the currency defined in `currency`. Read-only.", "required": true }, { "name": "refunds", "description": "An object containing the following fields:\n* `data` - A list of up to three refunds.\n* `has_more` - Indicates whether there are more than three refunds against this payment.\n* `total_count` - Total number of refunds against this payment.\n* `url` - URL for requesting all of the refunds against this payment.\nRead-only.", "type": [ { "type": "object", "fields": [ { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ] } ], "required": true }, { "name": "rewards", "type": [ { "type": "object" } ], "description": "Reserved.", "required": true }, { "name": "source_wallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is transferred from. String starting with **ewallet_**.", "required": true }, { "name": "src_currency", "description": "The source currency in transactions with foreign exchange.\nThree-letter ISO 4217 code for the currency. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "src_currency_symbol", "type": [ { "type": "string" } ], "description": "A URL link to the source-currency symbol.", "required": true }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "description": "A text description suitable for a customer's payment statement. Limited to 22 characters.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "CANCELED", "CLOSED" ] } ], "description": "Status of the transaction. One of the following:\n* **CANCELED**\n* **CLOSED**", "required": true }, { "name": "textual_codes", "type": [ { "type": "object", "fields": [ { "name": "code", "type": [ { "type": "unknown" } ] }, { "name": "pay_code", "type": [ { "type": "unknown" } ] }, { "name": "pairing_code", "type": [ { "type": "unknown" } ] }, { "name": "payment_code", "type": [ { "type": "unknown" } ] }, { "name": "response_code", "type": [ { "type": "unknown" } ] } ] } ], "description": "A set of text codes for the customer to use to complete the steps described in the `instructions` field.\nContains one or more of the following fields:\n* `code`\n* `pay_code` \n* `pairing_code` \n* `payment_code` \n* `response_code`\nRead-only.", "required": true }, { "name": "transaction_id", "type": [ { "type": "string" } ], "description": "ID of the associated transaction. Read-only.", "required": true }, { "description": "Type of transaction. See [Transaction Types](ref:transaction-types).", "type": [ { "type": "string" } ], "name": "type", "required": true }, { "name": "visual_codes", "type": [ { "type": "object" } ], "description": "A set of images for the customer to use to complete the steps described in the `instructions` field. For example, a QR code or barcode. Read-only.", "required": true } ] }, { "product": "disburse", "id": "payout-object", "type": "type", "name": "Payout", "description": "The Payout object describes a single payout transaction. It forms the basis for the disbursement process.", "fields": [ { "description": "ID of the Payout object. String starting with **payout_**.", "type": [ { "type": "string", "startsWith": "payout_" } ], "name": "id", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "Amount of the payout, in units defined by `payout_currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Same as `payout_amount`. Response only.", "required": true }, { "name": "amount_range_per_currency", "type": [ { "type": "object", "fields": [ { "name": "maximum_amount", "type": [ { "type": "unknown" } ] }, { "name": "minimum_amount", "type": [ { "type": "unknown" } ] }, { "name": "payout_currency", "type": [ { "type": "unknown" } ] } ] } ], "description": "An array of objects that describe limits on the amount, per currency. Contains the following fields:\n\\* `maximum_amount` - Maximum amount supported by this payout method for the indicated currency. Decimal number.\n\\* `minimum_amount` - Minimum amount supported by this payout method for the indicated currency. Decimal number.\n\\* `payout_currency` - Currency of the payout. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "batch_file_header", "type": [ { "type": "string" } ], "description": "Contains a comma-separated list of the headers required for creating a batch file. Relevant for creating a mass payout through the Client Portal.", "required": true }, { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" }, { "type": "object" } ], "description": "One of the following:\n\\* String starting with **beneficiary_**. The response to [Create Beneficiary](ref:create-beneficiary) provides the ID of the `beneficiary` object.\n\\* Object describing the beneficiary. Must include all fields in the [Beneficiary Object](ref:beneficiary-object), and all fields in the response to [Get Payout Required Fields](ref:get-payout-required-fields).", "required": true }, { "name": "beneficiary_country", "type": [ { "type": "string" } ], "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "beneficiary_entity_type", "type": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ], "description": "Filters the type of entity for the beneficiary. One of the following:\n\\* **company**\n\\* **individual**\n\nRelevant to [List Payout Method Types](ref:list-payout-method-types).", "required": true }, { "name": "beneficiary_entity_types", "type": [ { "type": "array", "arrayTypes": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ] } ], "description": "A list of the beneficiary entity types supported by this payout method. One or more of the following:\n\\* **company**\n\\* **individual**", "required": true }, { "name": "beneficiary_required_fields", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "Describes the fields required for the beneficiary when you create a payout. Two or more of the following:\n\\* `name` - Name of the field.\n\\* `regex` - A regular expression that defines the valid values for the field.\n\\* `type` - Type of data for the field.\n\\* `description` - Text description of the field.", "required": true }, { "name": "category", "type": [ { "type": "string", "possibleValues": [ "bank", "card", "cash", "ewallet", "rapyd_ewallet" ] } ], "description": "The category of payout method type. One of the following:\n\\* **bank**\n\\* **card**\n\\* **cash**\n\\* ** ewallet** - local eWallet\n\\* **rapyd_ewallet** - Rapyd wallet", "required": true }, { "name": "confirm_automatically", "type": [ { "type": "boolean" } ], "description": "Determines whether completion of the payout requires confirmation of the FX rate. One of the following:\n\\* **true** - The transaction is completed immediately.\n\\* **false** - The FX rate is confirmed by a separate API call to [Confirm Payout with FX](ref:confirm-payout-with-fx). This is the default.\n\nRelevant to payouts with FX.", "required": true }, { "name": "country", "type": [ { "type": "string" } ], "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the 'payout' object, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase.", "name": "currency", "type": [ { "type": "string" } ], "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the payout transaction.", "required": true }, { "name": "direction", "type": [ { "type": "string", "possibleValues": [ "ASC", "DESC" ] } ], "description": "Determines the order in which the files are returned. One of the following:\n\\* **ASC** - Ascending.\n\\* **DESC** - Descending. This is the default.", "required": true }, { "name": "ending_before", "type": [ { "type": "string", "startsWith": "payout_" } ], "description": "ID of the Payout object after the last one in the list. String starting with **payout_**.", "required": true }, { "name": "error", "type": [ { "type": "string" } ], "description": "Indicates the error code of the last unsuccessful operation on the Payout object.", "required": true }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is transferred from. String starting with **ewallet_**.", "required": true }, { "name": "ewallets", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "An array of one object, which contains the following fields:\n\\* **ewallet_id** - The ID of the wallet that the money is transferred from, a string starting with **ewallet_**.\n\\* **amount** - Amount of the transaction in currency units defined in `currency`.\n\\* **percent** - A decimal number representing a percentage of the total payout.\n\nResponse only.", "required": true }, { "name": "expiration", "type": [ { "type": "number" } ], "description": "Determines the time which the payout must be completed by, in [*Unix time*](ref:glossary).\n\nRelevant to all payout methods where the `is_expirable` field is **true** in the response to [List Payout Method Types](ref:list-payout-method-types).", "required": true }, { "name": "fx_rate", "type": [ { "type": "number" } ], "description": "Currency conversion rate for the payout. Decimal. Response only.", "required": true }, { "name": "image", "type": [ { "type": "string" } ], "description": "URL of an image that the merchant can use to represent the payout method.", "required": true }, { "name": "instructions", "type": [ { "type": "object" } ], "description": "Describes how the customer collects the payout. \n\nContains the following fields:\n\\* **name** - Short description of the instructions.\n\\* **steps** - A 'steps' object containing a list of steps for the customer to take. Each step is named step*N*, where *N* is an integer.", "required": true }, { "description": "Additional information from the merchant. For example, the merchant's instructions and transaction number that must be presented for collecting the payout.", "type": [ { "type": "object" } ], "name": "instructions_value", "required": true }, { "name": "is_cancelable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout can be canceled. Relevant when `category` is **cash**.", "required": true }, { "name": "is_expirable", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout expires if not completed. Relevant when `category` is **cash**.", "required": true }, { "name": "is_location_specific", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout must be made at a specific physical location. Relevant when `category` is **cash**.", "required": true }, { "name": "is_online", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout is made automatically, without any action by the beneficiary. Response only.", "required": true }, { "name": "limit", "type": [ { "type": "number" } ], "description": "Maximum number of payout object IDs to return. Integer.", "required": true }, { "name": "maximum_amount", "type": [ { "type": "number" } ], "description": "Maximum amount supported by this payout method for the indicated currency. Decimal number.", "required": true }, { "name": "maximum_expiration_seconds", "description": "The maximum time (in seconds) that the merchant can set for completing the payout. Relevant when `is_expirable` is **true**. Response only.", "type": [ { "type": "number" } ], "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "ID defined by the client. Limited to 255 characters.", "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "minimum_amount", "type": [ { "type": "number" } ], "description": "Minimum amount supported by this payout method for the indicated currency. Decimal number.", "required": true }, { "name": "minimum_expiration_seconds", "type": [ { "type": "number" } ], "description": "The minimum time (in seconds) that the merchant can set for completing the payout. Relevant when `is_expirable` is **true**. Response only.", "required": true }, { "name": "paid_amount", "type": [ { "type": "number" } ], "description": "Cumulative amount received by the beneficiary, in units defined by `payout_currency`. Response only.", "required": true }, { "description": "Time of the payout, in [*Unix time*](ref:glossary). Response only.", "type": [ { "type": "number" } ], "name": "paid_at", "required": true }, { "name": "payout_amount", "type": [ { "type": "number" } ], "description": "Amount received by the beneficiary, in units of the currency defined in `payout_currency`. Mandatory when `sender_amount` is not used. Decimal.", "required": true }, { "name": "payout_currency", "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "payout_currencies", "type": [ { "type": "array", "arrayTypes": [ { "type": "string" } ] } ], "description": "A list of the currencies supported by this payout method. Three-letter ISO 4217 code. Uppercase.", "required": true }, { "name": "payout_fees", "type": [ { "type": "object" } ], "description": "Reserved.", "required": true }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "description": "The type of payout method.", "required": true }, { "name": "payout_options", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "fields": [ { "name": "name", "type": [ { "type": "unknown" } ] }, { "name": "type", "type": [ { "type": "unknown" } ] }, { "name": "regex", "type": [ { "type": "unknown" } ] }, { "name": "description", "type": [ { "type": "unknown" } ] }, { "name": "is_required", "type": [ { "type": "unknown" } ] }, { "name": "is_updateable", "type": [ { "type": "unknown" } ] } ] } ] } ], "description": "Additional information about fields used in creating the specific payout method. Each object represents a field and contains the following fields:\n\\* `name` - Name of the field.\n\\* `type` - Type of the field (boolean, number, string).\n* `regex` - A regular expression that defines the format, when `type` is **string**.\n\\* `description` - Description of the field.\n\\* `is_required` - Whether the field is required for adding the payout method.\n\\* `is_updateable` - Indicates whether the field can be updated with [Update Payout](ref:update-payout).", "required": true }, { "name": "payout_type", "type": [ { "type": "string" } ], "description": "The type of the payout method.", "required": true }, { "name": "result", "description": "Determines which file is retrieved from the platform.\n\\* **true** - Returns the result file.\n\\* **false** - Returns the original uploaded batch file.", "type": [ { "type": "string" } ], "required": true }, { "name": "sender", "type": [ { "type": "string", "startsWith": "sender_" }, { "type": "object" } ], "description": "One of the following:\n\\* String starting with **sender_**. The response to [Create Sender](ref:create-sender) provides the ID of the 'sender' object.\n\\* Object describing the sender. Must include all fields in the [Sender Object](ref:sender-object), and all fields in the response to [Get Payout Required Fields](ref:get-payout-required-fields).", "required": true }, { "name": "sender_amount", "type": [ { "type": "number" } ], "description": "Amount that the sender is paying in units of the currency defined in `sender_currency`. This amount remains the same regardless of FX fees. Required when `payout_amount` is not used. Decimal.", "required": true }, { "name": "sender_country", "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase.", "type": [ { "type": "string" } ], "required": true }, { "name": "sender_currency", "description": "Currency that the sender is paying with. Currency consists of a three-letter ISO 4217 code. Uppercase.", "type": [ { "type": "object" } ], "required": true }, { "name": "sender_entity_type", "description": "Filters the type of entity for the sender. One of the following:\n\\* **company**\n\\* **individual**\n\nRelevant to [List Payout Method Types](ref:list-payout-method-types).", "type": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ], "required": true }, { "name": "sender_entity_types", "type": [ { "type": "array", "arrayTypes": [ { "type": "string", "possibleValues": [ "company", "individual" ] } ] } ], "description": "A list of the sender entity types supported by this payout method. One or more of the following:\n\\* **company**\n\\* **individual**", "required": true }, { "name": "sender_required_fields", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "description": "Describes the fields required for the sender when you create a payout. Two or more of the following:\n\\* `name` - Name of the field.\n\\* `regex` - A regular expression that defines the valid values for the field.\n\\* `type` - Type of data for the field.\n\\* `description` - Text description of the field.", "required": true }, { "description": "ID of the Payout object before the first one in the list. String starting with **payout_**.", "type": [ { "type": "string", "startsWith": "payout_" } ], "name": "starting_after", "required": true }, { "type": [ { "type": "string" } ], "description": "A statement that includes the reason for the payout. Limited to 35 characters.", "name": "statement_descriptor", "required": true }, { "name": "status", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payout method is currently available. One of the following values:\n\\* **false** - Not available.\n\\* **true** - Available.\n\nRelevant to [List Payout Method Types](ref:list-payout-method-types).", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "Confirmation", "Created", "Completed", "Canceled", "Error", "Expired" ] } ], "description": "Indicates the status of the payout. Response only.\nOne of the following:\n\\* **Confirmation** - The payout is waiting for a confirmation of the FX rate.\n\\* **Created** - The payout was created successfully. \n\\* **Completed** - The beneficiary received some or all payout funds.\n\\* **Canceled** - The payout was canceled.\n\\* **Error** - The payout was not created or failed after creation.\n\\* **Expired** - The payout has expired.", "required": true } ] }, { "product": "disburse", "parent": "payout-object", "id": "create-payout", "type": "request", "name": "CreatePayoutRequest", "description": "Use the POST method to create a payout.\n\n> **Note:** Before you call this method, you must determine which payout methods are valid for the country, and which fields are required for the payout method. Use the following methods:\n> * [List Payout Method Types](ref:list-payout-method-types) \n> * [Get Payout Required Fields](ref:get-payout-required-fields)\n\nIf you create a payout with FX and `confirm_automatically` is set to **false**, you must run [Confirm Payout with FX](ref:confirm-payout-with-fx) within a short time. The exact amount of time varies from payout method to payout method.\n\nThis method triggers the **Payout Created** webhook. This webhook contains the same information as the response. If the action of a third party is not required, the **Payout Completed** webhook is also triggered.\n\nThe following asynchronous webhooks provide information about later changes to the Payout object:\n\n* [Webhook - Payout Completed](ref:webhook-payout-completed) \n* [Webhook - Payout Expired](ref:webhook-payout-expired) \n* [Webhook - Payout Failed](ref:webhook-payout-failed) \n* [Webhook - Payout Returned](ref:webhook-payout-returned) \n\nTo complete your simulation in the sandbox, you must run [Complete Payout](ref:complete-payout) if the payout method requires the action of a third party.\n \n> **Note:** Clients with [PCI](ref:glossary) certification can make a payout to a card.", "method": "POST", "path": "/v1/payouts", "params": [], "body": [ { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "required": true, "description": "String starting with **beneficiary_** or the object describing the beneficiary." }, { "name": "beneficiary_country", "type": [ { "type": "string" } ], "required": false, "description": "Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "beneficiary_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the beneficiary. One of the following: **individual**, **company**" }, { "name": "confirm_automatically", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether completion of the payout requires confirmation of the FX rate. Relevant to payouts with foreign exchange. Default is false." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the payout transaction." }, { "name": "expiration", "type": [ { "type": "string" } ], "required": false, "description": "Determines the time in which the payout must be completed, in [*Unix time*](ref:glossary). Relevant to cash payouts." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "ID of the wallet that the money is transferred from. String starting with **ewallet_**." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "ID defined by the client. Limited to 255 characters." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payout_amount", "type": [ { "type": "number" } ], "required": false, "description": "Amount of the payout, in units of the currency defined in `payout_currency`. Mandatory when `sender_amount` is not used. Decimal." }, { "name": "payout_currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency received by the beneficiary. Three-letter ISO 4217 code. Uppercase." }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "required": true, "description": "The type of payout method." }, { "name": "sender", "type": [ { "type": "string", "startsWith": "sender_" } ], "required": true, "description": "String starting with **sender_** or the object describing the sender." }, { "name": "sender_amount", "type": [ { "type": "number" } ], "required": false, "description": "Amount that the sender is paying in units of the currency defined in `sender_currency`. This amount remains the same regardless of FX fees. Required when `payout_amount` is not used. Decimal." }, { "name": "sender_country", "type": [ { "type": "string" } ], "required": true, "description": "Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase." }, { "name": "sender_currency", "type": [ { "type": "string" } ], "required": true, "description": "Currency that the sender is paying with. Three-letter ISO 4217 code. Uppercase." }, { "name": "sender_entity_type", "type": [ { "type": "string" } ], "required": true, "description": "Type of entity for the sender. One of the following: **individual**, **company**" }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "A statement that includes the reason for the payout. Limited to 35 characters." } ], "headers": [], "query": [] }, { "product": "disburse", "parent": "payout-object", "id": "confirm-payout-with-fx", "type": "request", "name": "ConfirmPayoutWithFXRequest", "description": "Use the POST method to confirm the exchange rate of a payout that involves foreign exchange. Relevant when the payout was created with `confirm_automatically` set to **false**. You must run this method within a short time. The exact amount of time varies from payout method to payout method.\n\nThis method triggers the **Payout Created** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/payouts/confirm/{payout}", "params": [ { "name": "payout", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": true, "description": "ID of the payout. String starting with **payout_**." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "payout-object", "id": "complete-payout", "type": "request", "name": "CompletePayoutRequest", "description": "Use this method in the sandbox to simulate the action of a third party that is required for completing the payout process.\n\nRelevant when the status of the payout is **Created**. \n\n**Prerequisites:**\n* [Create Wallet](ref:create-wallet) \n* [Add Funds to Wallet Account](ref:add-funds-to-wallet-account) \n* [Create Payout](ref:create-payout) \n\nThis method triggers the **Payout Completed** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/payouts/complete/{payout}/{amount}", "params": [ { "name": "payout", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": true, "description": "ID of the payout. String starting with **payout_**." }, { "name": "amount", "type": [ { "type": "string" } ], "required": true, "description": "The payout amount. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "payout-object", "id": "retrieve-payout", "type": "request", "name": "RetrievePayoutRequest", "description": "Use the GET method to retrieve a payout.", "method": "GET", "path": "/v1/payouts/{payout}", "params": [ { "name": "payout", "type": [ { "type": "string" } ], "required": true, "description": "ID of the payout. String starting with *payout_*." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "payout-object", "id": "cancel-payout", "type": "request", "name": "CancelPayoutRequest", "description": "Use the DELETE method to cancel a payout. The payout can be canceled unless its status is **confirmation** or **completed**.\n\nThis method triggers the **Payout Canceled** webhook. This webhook contains the same information as the response.", "method": "DELETE", "path": "/v1/payouts/{payout}", "params": [ { "name": "payout", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": true, "description": "ID of the payout. String starting with **payout_**." } ], "body": [], "headers": [], "query": [] }, { "product": "disburse", "parent": "payout-object", "id": "list-payouts", "type": "request", "name": "ListPayoutsRequest", "description": "Use the GET method to retrieve a list of payouts that you created. The list can include up to 100 payouts.", "method": "GET", "path": "/v1/payouts", "params": [], "body": [], "headers": [], "query": [ { "name": "beneficiary", "type": [ { "type": "string", "startsWith": "beneficiary_" } ], "required": false, "description": "Filters according to the beneficiary ID. String starting with **beneficiary_**." }, { "name": "ending_before", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": false, "description": "The ID of a payout in the list. The list ends with the payout that was created before the payout with this ID. Use this filter to get the previous page of results. String starting with **payout_**." }, { "name": "ewallet", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "required": false, "description": "Filters according to the wallet ID. String starting with **ewallet_**." }, { "name": "invoice", "type": [ { "type": "string", "startsWith": "invoice_" } ], "required": false, "description": "Filters according to the invoice. String starting with **invoice_**." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of payouts to return. Range: 1-100. Default is 10." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "Filters according to the merchant reference ID." }, { "name": "payout_method_type", "type": [ { "type": "string" } ], "required": false, "description": "Filters according to the type of payout method." }, { "name": "sender", "type": [ { "type": "string", "startsWith": "sender_" } ], "required": false, "description": "Filters according to the sender ID. String starting with **sender_**." }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "payout_" } ], "required": false, "description": "The ID of a payout in the list. The list begins with the payout that was created next after the payout with this ID. Use this filter to get the next page of results. Relevant when `ending_before` is not used. String starting with **payout_**." }, { "name": "subscription", "type": [ { "type": "string", "startsWith": "sub_" } ], "required": false, "description": "Filters according to the subscription ID. String starting with **sub_**." } ] }, { "product": "disburse", "parent": "payout-object", "id": "payout-errors-1", "type": "enum", "name": "PayoutError", "values": [ { "name": "ERROR_BENEFICIARY_DETAILS_IN_REQUEST_AND_SAVED_BENEFICIARY_DETAILS_MISMATCH", "description": "The request attempted an operation that requires a beneficiary ID, but the details in the request do not match the details in the saved beneficiary object. The request was rejected. Corrective action: Use the values that were saved in the beneficiary object or create a new beneficiary." }, { "name": "ERROR_CANCEL_PAYOUT", "description": "The request tried to cancel a payout, but the payout type was not cancelable or the payout was in 'confirmed' or 'completed' status. The request was rejected. Corrective action: None. Determine why an attempt was made to cancel a payout that was not cancelable. " }, { "name": "ERROR_CONFIRM_PAYOUT", "description": "The request tried to confirm a payout with foreign exchange, but the payout was already completed or did not involve foreign exchange. The request was rejected. Corrective action: None. Determine why an attempt was made to confirm the foreign exchange rate in a payout that does not involve foreign exchange." }, { "name": "ERROR_CREATE_BENEFICIARY_COUNTRY_NOT_VALID", "description": "The request tried to create a beneficiary for a payout, but the country was not recognized. The request was rejected. Corrective action: Use the correct 2-letter ISO 3166-1 ALPHA-2 code, in uppercase letters, for the 'country' field." }, { "name": "ERROR_CREATE_BENEFICIARY_CURRENCY_NOT_VALID", "description": "The request tried to create a beneficiary for a payout, but the currency was missing or not recognized. The request was rejected. Corrective action: Use the correct 3-letter ISO 4217 code for the currency, in uppercase letters, for the 'currency' field." }, { "name": "ERROR_CREATE_PAYOUT", "description": "The request tried to create a payout, but a required field was missing or a field had an incorrect value. The request was rejected. Corrective action: Run 'Get Payout Required Fields' and check all values." }, { "name": "ERROR_CREATE_PAYOUT_ABA_CONTAINS_NON_NUMERIC_CHARACTERS", "description": "The request tried to create a payment with a card that requires 3DS authentication, but the authentication failed. The request was rejected. Corrective action: Try the request again. If the error persists, assess the security risk." }, { "name": "ERROR_CREATE_PAYOUT_ABA_LENGTH_NOT_VALID", "description": "The request tried to create a payout, but the ABA code for the beneficiary is not valid. The request was rejected. Corrective action: Set 'aba' to a string of 9 numerals." }, { "name": "ERROR_CREATE_PAYOUT_AMOUNT_UNKNOWN", "description": "The request tried to create a payout with FX, but the amount of the transaction could not be determined. The request was rejected. Corrective action: Specify 'sender_amount' or 'payout_amount', but not both." }, { "name": "ERROR_CREATE_PAYOUT_COUNTRY_NOT_SUPPORTED", "description": "The request tried to create a payout, but the country of the sender or beneficiary is not supported for the payout method selected. The request was rejected. Corrective action: Use a payout method that supports both the sender country and the beneficiary country." }, { "name": "ERROR_CREATE_PAYOUT_CURRENCY_NOT_SUPPORTED", "description": "The request tried to create a payout, but the sender currency or the payout currency is not supported for the payout method selected. The request was rejected. Corrective action: Use a payout method that supports both the sender currency and the payout currency." }, { "name": "ERROR_CREATE_PAYOUT_PURPOSE_CODE_NOT_VALID", "description": "The request tried to create a payout, but the purpose code for the sender is not valid. The request was rejected. Corrective action: Set 'purpose_code' to a valid value." }, { "name": "ERROR_CREATE_PAYOUT_TO_CARD_BANK_NOT_SUPPORTED", "description": "The request tried to create a payout to a card, but the card issuer has not enabled the bank to offer the service of receiving funds. The request was rejected. Corrective action: Contact Rapyd Client Support." }, { "name": "ERROR_CREATE_PAYOUT_TO_CARD_CONTACT_ISSUER", "description": "The request tried to create a payout to a card, but there was a problem with the card. The request was rejected. Corrective action: Advise the cardholder to contact the issuer." }, { "name": "ERROR_CREATE_PAYOUT_TO_CARD_EXPIRED_CARD", "description": "The request tried to create a payout to a card, but the card expired. The request was rejected. Corrective action: Advise the cardholder to contact the issuer." }, { "name": "ERROR_CREATE_PAYOUT_TO_CARD_NUMBER_NOT_VALID", "description": "The request tried to create a payout to a card, but the card number was not valid. The request was rejected. Corrective action: Advise the cardholder to contact the issuer." }, { "name": "ERROR_CREATE_PAYOUT_TO_CARD_SERVICE_NOT_SUPPORTED", "description": "The request tried to create a payout to a card, but the card issuer has not enabled the card to receive funds. The request was rejected. Corrective action: Advise the cardholder to contact the issuer." }, { "name": "ERROR_CREATE_SENDER_COUNTRY_NOT_VALID", "description": "The request tried to create a sender for a payout, but the country was missing or not recognized. The request was rejected. Corrective action: For the country, use the correct 2-letter ISO 3166-1 ALPHA-2 code, in uppercase letters." }, { "name": "ERROR_CREATE_SENDER_CURRENCY_NOT_VALID", "description": "The request tried to create a sender for a payout, but the currency was missing or not recognized. The request was rejected. Corrective action: For the currency, use the correct 3-letter ISO 4217 code, in uppercase letters." }, { "name": "ERROR_DELETE_PAYOUT_BENEFICIARY", "description": "The request tried to delete a beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary." }, { "name": "ERROR_EXPIRATION_SENT_FOR_NON_CASH_PAYOUT", "description": "The request tried to create a payout for a category other than 'cash', but an expiration time was set. The request was rejected. Corrective action: Create the payout without setting the 'expiration' field." }, { "name": "ERROR_GET_BENEFICIARY", "description": "The request attempted an operation that requires a payout beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary." }, { "name": "ERROR_GET_PAYER", "description": "The request attempted an operation that requires a payout sender, but the sender was not found. The request was rejected. Corrective action: Use the ID of a valid sender." }, { "name": "ERROR_GET_PAYOUT", "description": "The request tried to retrieve a payout, but the payout was not found. The request was rejected. Corrective action: Use the ID of a valid payout." }, { "name": "ERROR_INVALID_PAYOUT_BENEFICIARY_ENTITY_TYPE", "description": "The request tried to create a beneficiary for a payout, but the entity type was not recognized. The request was rejected. Corrective action: Set the beneficiary entity type to 'company' or 'individual'." }, { "name": "ERROR_INVALID_PAYOUT_SENDER_ENTITY_TYPE", "description": "The request tried to create a sender for a payout, but the entity type was not recognized. The request was rejected. Corrective action: Set the sender entity type to 'company' or 'individual'." }, { "name": "ERROR_LOCATION_PROVIDED_FOR_PAYOUT_THAT_IS_NOT_LOCATION_SPECIFIC", "description": "The request tried to create a payout, but the request included a location and the payout method type is not location-specific. The request was rejected. Corrective action: Delete 'location' from the request or use a payout method type that is location-specific." }, { "name": "ERROR_MISSING_OR_INVALID_PAYOUT_AMOUNT", "description": "The request attempted an operation that requires the amount of the payout, but the amount was not recognized. The request was rejected. Corrective action: Set 'amount' to the amount of the payout." }, { "name": "ERROR_MISSING_PAYOUT_AMOUNT", "description": "The request attempted an operation that requires the payout amount, but the payout amount was not set. The request was rejected. Corrective action: Use a positive decimal number for 'payout_amount'." }, { "name": "ERROR_MISSING_PAYOUT_BENEFICIARY_COUNTRY", "description": "The request attempted an operation that requires the country of the beneficiary, but the country was not found. The request was rejected. Corrective action: For the 'country' field, use the 2-letter ISO 3166-1 ALPHA-2 code, in uppercase letters." }, { "name": "ERROR_MISSING_PAYOUT_BENEFICIARY_ENTITY_TYPE", "description": "The request attempted an operation that requires the entity type of the beneficiary, but the entity type was not found. The request was rejected. Corrective action: Set the beneficiary entity type to 'individual' or 'company'." }, { "name": "ERROR_MISSING_PAYOUT_CURRENCY", "description": "The request tried to create a payout, but the payout currency was missing. The request was rejected. Corrective action: For 'payout_currency', use the 3-letter ISO 4217 code, in uppercase letters." }, { "name": "ERROR_MISSING_PAYOUT_LOCATION", "description": "The request tried to create a payout to a specific location, but 'location_id' was not set. The request was rejected. Corrective action: Provide a valid string for 'location_id'." }, { "name": "ERROR_MISSING_PAYOUT_METHOD_TYPE", "description": "The request tried to create a payout, but 'payout_method_type' was not set. The request was rejected. Corrective action: Provide a valid string for 'payout_method_type'." }, { "name": "ERROR_MISSING_PAYOUT_SENDER_COUNTRY", "description": "The request attempted an operation that requires the country of the sender, but the country was missing. The request was rejected. Corrective action: For 'sender_country', use the 2-letter ISO 3166-1 ALPHA-2 code for the country, in uppercase letters." }, { "name": "ERROR_MISSING_PAYOUT_SENDER_CURRENCY", "description": "The request attempted an operation that requires the currency of the sender, but the currency was missing. The request was rejected. Corrective action: For 'sender_currency', use the 3-letter ISO 4217 code for the currency, in uppercase letters." }, { "name": "ERROR_MISSING_PAYOUT_SENDER_ENTITY_TYPE", "description": "The request attempted an operation that requires the entity type of the sender, but the entity type was not found. The request was rejected. Corrective action: Set the sender entity type to 'individual' or 'company'." }, { "name": "ERROR_MISSING_PAYOUT_UPDATE_FIELDS", "description": "The request tried to update a payout, but both the description and the metadata were missing. The request was rejected. Corrective action: Provide either the description or metadata, or both." }, { "name": "ERROR_PAYER_DETAILS_IN_REQUEST_AND_SAVED_PAYER_DETAILS_MISMATCH", "description": "The request tried to create a payout, but the details in the payer did not match the details in the request. The request was rejected. Corrective action: Use the same currency and country for the payout and the sender. If the payer was previously saved, use 'Retrieve Sender' to get the values." }, { "name": "ERROR_PAYOUT_AMOUNT_EXCEEDED_ORIGINAL_AMOUNT", "description": "The request tried to complete a payout in the sandbox, but the total amount of the payout has already been paid out. The request was rejected. Corrective action: Create another payout." }, { "name": "ERROR_PAYOUT_AMOUNT_LESS_THAN_MINIMUM", "description": "The request attempted an operation that requires an amount, but the amount was less than the minimum required for the type of payout method. The request was rejected. Corrective action: Use an amount that is more than the minimum. To determine the minimum, run 'Get Payout Required Fields'." }, { "name": "ERROR_PAYOUT_AMOUNT_MORE_THAN_MAXIMUM", "description": "The request attempted an operation that requires an amount, but the amount was more than the maximum required for the type of payout method. The request was rejected. Corrective action: Use an amount that is less than the maximum. To determine the maximum, run 'Get Payout Required Fields'." }, { "name": "ERROR_PAYOUT_AMOUNT_NOT_WITHIN_RANGE_OF_PAYOUT_METHOD_TYPE", "description": "The amount provided was not within the range of the payout method type. The request was rejected. Corrective action: Ensure that the amount provided is within the range of the payout method type." }, { "name": "ERROR_PAYOUT_BENEFICIARY_FIELDS_NOT_FOUND", "description": "The request tried to create a payout, but some of the items specified in the request were not found. The request was rejected. Corrective action: Check your input data. The beneficiary fields with incorrect data appear at the end of the error code." }, { "name": "ERROR_PAYOUT_BENEFICIARY_FIELDS_NOT_VALID", "description": "The request tried to create a payout, but some of the items specified in the request did not have valid values. The request was rejected. Corrective action: Check your input data. The beneficiary fields with incorrect data appear at the end of the error code." }, { "name": "ERROR_PAYOUT_CURRENCY_NOT_SUPPORTED", "description": "The request attempted an operation that requires the payout currency, but the payout method does not support the currency selected for the country of the beneficiary. The request was rejected. Corrective action: Run 'List Payout Method Types'." }, { "name": "ERROR_PAYOUT_NAME_NOT_VALID", "description": "The request tried to create a payout, but the name of the beneficiary or sender was not valid. The request was rejected. Corrective action: Verify that 'name' is correct in the explicit sender and beneficiary objects in the request, or that 'first_name', 'last_name' and 'company_name' are correct in the beneficiary and sender objects that are referenced by ID." }, { "name": "ERROR_PAYOUT_NOT_CANCELABLE", "description": "The request tried to cancel a payout, but the payout method type does not support cancellation. The request was rejected. Corrective action: To collect money from the beneficiary, use 'Create Payment'." }, { "name": "ERROR_UNSUPPORTED_PAYOUT_CURRENCY_OR_COUNTRY", "description": "The request attempted a payout operation, but there was a problem with the country or currency, or a mismatch in entity types. The request was rejected. Corrective action: Run 'List Payout Method Types'. Use only supported countries, and use only currencies that are supported for each country. If you are using saved entities for payer or beneficiary, make sure the entity type in the request matches the entity type in the saved entity." }, { "name": "ERROR_UPDATE_PAYOUT", "description": "The request tried to update a payout, but the payout was not found. The request was rejected. Corrective action: For the 'payout' path parameter, use the ID of a valid payout, a string starting with 'payout_'." }, { "name": "ERROR_VALIDATE_PAYOUT_BENEFICIARY", "description": "The request tried to validate a beneficiary, but there was an error in the input fields. The request was rejected. Corrective action: Run 'Get Payout Required Fields'." }, { "name": "ERROR_UPDATE_NON_ACTIVE_PAYOUT", "description": "The request tried to update a payout, but the status of the payout was not 'created'. The request was rejected. Corrective action: Determine why an attempt was made to update a payout that was completed or canceled, or has a status of 'error'." }, { "name": "INVALID_BENEFICIARY_PAYOUT_ENTITY_TYPE", "description": "The request attempted an operation that requires the entity type of the beneficiary, but the value was not found or not recognized. The request was rejected. Corrective action: Set the 'beneficiary_entity_type' field to one of the following values: 'individual', 'company'." }, { "name": "INVALID_DESTINATION_CURRENCY", "description": "The request attempted an operation that requires the code of the currency to pay out, but the currency was not recognized. The request was rejected. Corrective action: Use the correct 3-letter ISO 4217 code for the currency, in uppercase letters." }, { "name": "INVALID_PAYER_FIELDS", "description": "The request attempted an operation that requires a sender, but one of the fields in the 'sender' object contained a value that is not valid. The request was rejected. Corrective action: The name of the field appears at the end of the response code. Use a valid value." }, { "name": "INVALID_PAYER_PAYOUT_ENTITY_TYPE", "description": "The request attempted an operation that requires the entity type of the sender, but the value was not found or not recognized. The request was rejected. Corrective action: Set the sender entity type to one of the following values: 'individual', 'company'." }, { "name": "INVALID_PAYOUT", "description": "The request tried to create a payout, but the 'payout_type' parameter was not found. The request was rejected. Corrective action: Use the correct payout type." }, { "name": "INVALID_PAYOUT_CURRENCIES", "description": "The request tried to create a payout, but the sender currency or the payout currency is not supported for the payout method type specified. The request was rejected. Corrective action: Choose a payout method type from the response to 'List Payout Method Types', and select currencies that are supported for the payout method type you want." }, { "name": "INVALID_PAYOUT_METHOD_TYPE", "description": "The request tried to create a payout, but the payout method type was not recognized. The request was rejected. Corrective action: Run 'List Payout Method Types'." }, { "name": "INVALID_PAYOUT_TYPE", "description": "The request attempted an operation that requires a payout category, but the payout category was not found. The request was rejected. Corrective action: Set 'category' to one of the following values: 'bank', 'card’, 'cash', 'ewallet', 'rapyd_ewallet'" }, { "name": "INVALID_REQUIRED_FIELD", "description": "The request attempted a payout operation, but the value of one of the fields was not valid. The request was rejected. Corrective action: The name of the problematic field appears at the end of the error code. Provide a value that matches the regex defined in the response to 'Get Payout Required Fields'." }, { "name": "MISSING_PAYOUT_BENEFICIARY_COUNTRY", "description": "The request attempted an operation that requires the country of the beneficiary, but the value was not found or not recognized. The request was rejected. Corrective action: Use the correct 2-letter ISO 3166-1 ALPHA-2 code, in uppercase letters, for the 'beneficiary_country' field." }, { "name": "MISSING_PAYOUT_METHOD_REQUIRED_FIELDS", "description": "The request tried to create a payout, but one or more required fields were missing. The request was rejected. Corrective action: The names of the missing fields appear at the end of the error code. For the correct values, see the API Reference and the response to 'Get Payout Required Fields'." }, { "name": "PAYOUT_METHOD_TYPE_BENEFICIARY_COUNTRY_MISMATCH", "description": "The request tried to create a payout, but the payout method type is not supported for the beneficiary country. The request was rejected. Corrective action: Run 'List Supported Payout Types' for the country of the beneficiary. The response lists the supported payout method types." } ] }, { "product": "collect", "id": "payment-object", "type": "type", "name": "Payment", "description": "A payment collects funds from a source (called the payment method) and deposits them in one or more Rapyd Wallets. The entire process is managed with methods in the Payment object.", "fields": [ { "description": "ID of the payment. String starting with **payment_**. Response only.", "type": [ { "type": "string", "startsWith": "payment_" } ], "name": "id", "required": true }, { "name": "address", "type": [ { "type": "object", "id": "address-object" } ], "description": "Billing address associated with this specific payment.\n\nFor more information, see [Address Object](ref:address-object).", "required": true }, { "name": "amount", "type": [ { "type": "number" } ], "description": "The amount received by the recipient, in units of the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. To verify a card, set to **0**.", "required": true }, { "name": "cancel_reason", "type": [ { "type": "string" } ], "description": "Reason for cancellation or reversal of a payment. Response only.\n\nSee ***cancel_reason - Reversal Values***, below.", "required": true }, { "name": "capture", "type": [ { "type": "boolean" } ], "description": "Determines when the payment is processed for capture. Relevant to card payments.\n\\* **True**: Capture the payment immediately. This is the default.\n\\* **False**: Authorize the payment, then capture some or all of the payment at a later time, when the merchant runs the [Capture Payment](ref:capture-payment) method.\n\n**Note:** Some card payment methods do not support delayed capture.", "required": true }, { "name": "captured", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payment has been successfully captured. Response only.", "required": true }, { "name": "complete_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected for final steps in completing the operation. Provided by the client.\n\nRelevant to bank redirect payment methods.", "required": true }, { "name": "country_code", "description": "The country of the payment method. Two-letter ISO 3166-1 ALPHA-2 code. Uppercase. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "created_at", "type": [ { "type": "number" } ], "description": "Time of creation of the payment, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "currency", "type": [ { "type": "string" } ], "description": "Defines the currency for the amount received by the seller (merchant). Three-letter ISO 4217 code. Uppercase.\nIn FX transactions, when `fixed_side` is **buy**, it is the currency received by the merchant. When `fixed_side` is **sell**, it is the currency charged to the buyer. \nSee also `fixed_side` and `requested_currency` fields.\n\nThis value is reflected in the `currency_code` field of the response.", "required": true }, { "name": "currency_code", "type": [ { "type": "string" } ], "description": "Indicates the currency of the amount received by the recipient. Three-letter ISO 4217 code. Uppercase. Response only.", "required": true }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer who is making the payment. String starting with **cus_**. Required if `payment_method` is blank.\n\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "customer_token", "type": [ { "type": "string", "startsWith": "cus_" } ], "description": "ID of the customer who is making the payment. String starting with **cus_**. When a payment is created without an existing customer, the platform creates an anonymous customer with no payment methods. Read only.\nFor more information, see [Customer Object](ref:customer-object).", "required": true }, { "name": "description", "type": [ { "type": "string" } ], "description": "Description of the payment transaction.", "required": true }, { "name": "dispute", "type": [ { "type": "object" } ], "description": "Details about the dispute, if the payment was disputed. Response only.", "required": true }, { "name": "ending_before", "type": [ { "type": "string", "startsWith": "payment_" } ], "description": "The ID of the payment created after the last payment you want to retrieve. String starting with **payment_**.\n\nRelevant to [List Payments](ref:list-payments).", "required": true }, { "name": "error_payment_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected in case of an error in the operation. Provided by the client.\n\nRelevant to bank redirect payment methods.", "required": true }, { "name": "escrow", "type": [ { "type": "boolean" } ], "description": "Determines whether the payment is held in escrow for later release. To release escrow funds immediately, use 'Update Payment' and set `escrow` to **false**. Relevant for card payments.", "required": true }, { "name": "escrow", "type": [ { "type": "object", "id": "escrow-object" } ], "description": "Describes the escrow. Relevant for card payments when the payment is created with `escrow` set to **true**. Response only.\nSee [Escrow Object](ref:escrow-object).", "required": true }, { "name": "escrow_release_days", "type": [ { "type": "number" } ], "description": "Determines the number of days after creation of the payment that funds are released from escrow. Funds are released at 5:00 pm GMT on the day indicated. Integer, range: 1-90.", "required": true }, { "name": "ewallet_id", "type": [ { "type": "string", "startsWith": "ewallet_" } ], "description": "ID of the wallet that the money is paid into. String starting with **ewallet_**. Response only.", "required": true }, { "name": "ewallets", "type": [ { "type": "array", "arrayTypes": [ { "type": "object", "id": "wallets-array" } ] } ], "description": "Specifies the wallets that the money is collected into. If this is left blank, the money goes into the oldest 'collection'-type client wallet. If there is no 'collection' client wallet, the money goes into the oldest 'general'-type client wallet.\n\nSee [Wallets Array](ref:wallets-array).", "required": true }, { "name": "expiration", "type": [ { "type": "number" } ], "description": "End of the time allowed for the customer to complete this payment, in [*Unix time*](ref:glossary). Default is 2 weeks.\n\nRelevant to all payment methods where the `is_expirable` field is **true** in the response to [List Payment Methods by Country](ref:list-payment-methods-by-country).", "required": true }, { "name": "failure_code", "type": [ { "type": "string" } ], "description": "Error code explaining the reason for failure of payment capture. Response only.", "required": true }, { "name": "failure_message", "description": "Message to the merchant, explaining the reason for failure of payment capture. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "fixed_side", "type": [ { "type": "string" } ], "description": "Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). \n\\* **buy** - The currency that the seller (merchant) receives for goods or services. Fixed side buy relates to the seller (merchant) funds. For example, a US-based merchant wants to charge 100 USD. The buyer (customer) pays the amount in MXN that converts to 100 USD.\n \n\\* **sell** - The currency that the buyer is charged with to purchase goods or services from the seller. Fixed side sell relates to the buyer (customer) funds. For example, a US-based merchant wants to charge a buyer 2,000 MXN and will accept whatever amount in USD that is converted from 2,000 MXN.\n\nSee also `requested_currency`.", "required": true }, { "name": "flow_type", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "fx_rate", "type": [ { "type": "string" } ], "description": "Exchange rate for the transaction. When `fixed_side` is **buy**, `fx_rate` is the buy rate. When `fixed_side` is **sell**, `fx_rate` is the sell rate.\nDecimal number as string. Response only.", "required": true }, { "name": "group", "type": [ { "type": "boolean" } ], "description": "When **true**, includes only group payments in the response. When **false**, excludes group payments from the response. Default is **false**.\n\nRelevant to [List Payments](ref:list-payments).", "required": true }, { "name": "group_payment", "type": [ { "type": "string", "startsWith": "gp_" } ], "description": "ID of the group payment. String starting with **gp_**. Relevant when the payment is part of a group payment. Response only.", "required": true }, { "name": "initiation_type", "type": [ { "type": "string", "possibleValues": [ "customer_present", "installment", "moto", "recurring", "unscheduled" ] } ], "description": "Indicates how the transaction was initiated. One of the following:\n\\* **customer_present** - The transaction was initiated by the customer. This is the default.\n\\* **installment** - The transaction was initiated by a subscription where there is a fixed number of installments.\n\\* **moto** - The transaction was initiated by mail order or by a telephone order and was initiated by the merchant or Rapyd client.\n\\* **recurring** - The transaction was initiated by a subscription where charges are made at regular intervals and there is no end date.\n\\* **unscheduled** - The transaction is a top-up transaction that was previously authorized by the cardholder and was initiated by the merchant or Rapyd client.", "required": true }, { "name": "instructions", "type": [ { "type": "object", "fields": [ { "name": "name", "type": [ { "type": "unknown" } ] }, { "name": "steps", "type": [ { "type": "unknown" } ] } ] } ], "description": "Describes how the customer makes the payment. Read-only. \n\nContains the following fields:\n\\* `name` - Description of the payment method.\n\\* `steps` - A `steps` object containing a list of steps for the customer to take. Each step is named **step*N***, where *N* is an integer.", "required": true }, { "name": "invoice", "type": [ { "type": "string", "startsWith": "inv_" } ], "description": "ID of the invoice that this payment is for. String starting with **inv_**. Response only.", "required": true }, { "name": "is_partial", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payment has been partially paid. When **false**, indicates that the payment is unpaid or fully paid. Response only.", "required": true }, { "name": "limit", "type": [ { "type": "string" } ], "description": "The maximum number of payments to return. Range: 1-100. Default is 10.\n\nRelevant to [List Payments](ref:list-payments).", "required": true }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "description": "ID defined by the client.. Limited to 255 characters.", "required": true }, { "name": "merchant_requested_amount", "description": "Indicates the amount paid by the payer, in units of the currency defined in `merchant_requested_currency`. Relevant to payments with FX. Read only.", "type": [ { "type": "number" } ], "required": true }, { "name": "merchant_requested_currency", "description": "Indicates the currency that merchant receives. Three-letter ISO 4217 code. Uppercase. Relevant to payments with FX. Response only.", "type": [ { "type": "string" } ], "required": true }, { "name": "metadata", "type": [ { "type": "object" } ], "description": "A JSON object defined by the client.", "required": true }, { "name": "mid", "type": [ { "type": "string" } ], "description": "Reserved.", "required": true }, { "name": "next_action", "type": [ { "type": "string", "possibleValues": [ "3d_verification", "pending_capture", "pending_confirmation", "not_applicable" ] } ], "description": "Indicates the next action for completing the payment. One of the following values:\n\\* **3d_verification** - The next action is 3DS. Relevant only to card payments.\n\\* **pending_capture** - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero.\n\\* **pending_confirmation** - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment.\n\\* **not_applicable** - The payment has completed or the next action is not relevant.", "required": true }, { "name": "order", "type": [ { "type": "string" } ], "description": "ID of the order that this payment is for. Read-only. Relevant when the payment is for an order.", "required": true }, { "name": "original_amount", "type": [ { "type": "number" } ], "description": "\\* **Foreign exchange payments** - The amount paid by the sender, in units of the currency defined in `requested_currency`, including gross transaction fees and gross FX fees. \n\\* **Payments not involving foreign exchange** - The amount of the payment, in units of the currency defined in `currency`, including gross transaction fees.\n\nResponse only.", "required": true }, { "name": "outcome", "description": "Describes the outcome of the risk assessment. Response only. \n\nSee [Outcome Object](ref:outcome-object).", "type": [ { "type": "object", "id": "outcome-object" } ], "required": true }, { "name": "paid", "type": [ { "type": "boolean" } ], "description": "Indicates whether the payment has been fully captured. Response only.", "required": true }, { "name": "paid_at", "type": [ { "type": "number" } ], "description": "Time of the last capture, in [*Unix time*](ref:glossary). Response only.", "required": true }, { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "description": "ID of the payment. String starting with **payment_**.", "required": true }, { "name": "payment_fees", "type": [ { "type": "object", "id": "payment-fees-object" } ], "description": "Object that defines transaction fees and foreign exchange fees. \nThese are fees that the Rapyd merchant can define for its consumers in addition to the payment amount. They are not related to the fees Rapyd charges to its clients. \n\nSee [Payment Fees Object](ref:payment-fees-object).", "required": true }, { "name": "payment_method", "type": [ { "type": "string" }, { "type": "object", "id": "payment-method-type-object" } ], "description": "`payment_method` ID or object. If not specified in this field, the payment method is the default payment method specified for the customer.\n\nThe `payment_method` object contains a `type` field and a `fields` object. For more information, see [Payment Method Type Object](ref:payment-method-type-object).", "required": true }, { "type": [ { "type": "object" } ], "name": "payment_method_data", "description": "Details of the `payment_method` object. Response only.", "required": true }, { "name": "payment_method_options", "type": [ { "type": "object", "id": "payment-method-type-object" } ], "description": "Object describing additional payment method fields required for the payment. These values are not saved as part of the payment method object. To determine the fields required, run [Get Payment Method Required Fields](ref:get-payment-method-required-fields).\n\nSee [Payment Method Type Object](ref:payment-method-type-object).", "required": true }, { "name": "payment_method_type", "type": [ { "type": "string" } ], "description": "The type of payment method. For a list of supported types for a country, run [List Payment Methods by Country](ref:list-payment-methods-by-country).", "required": true }, { "name": "payment_method_type_category", "type": [ { "type": "string", "possibleValues": [ "bank_transfer", "bank_redirect", "card", "cash", "ewallet" ] } ], "description": "Category of payment method type. Read-only. One of the following: \n\\* **bank_transfer** \n\\* **bank_redirect** \n\\* **card** \n\\* **cash**\n\\* **ewallet**", "required": true }, { "name": "receipt_email", "type": [ { "type": "string" } ], "description": "Email address that the receipt for this transaction is sent to.", "required": true }, { "name": "receipt_number", "type": [ { "type": "string" } ], "description": "Reserved. Response only.", "required": true }, { "name": "redirect_url", "type": [ { "type": "string" } ], "description": "URL where the customer is redirected for additional steps required for the payment. Response only.", "required": true }, { "name": "refunded", "type": [ { "type": "boolean" } ], "description": "Indicates whether there was a refund against this payment. Response only.", "required": true }, { "name": "refund_amount", "type": [ { "type": "string" } ], "description": "The total amount refunded against this payment, in units of the currency defined in `currency`. Response only.", "required": true }, { "name": "refunded_amount", "type": [ { "type": "number" } ], "description": "The total amount refunded against this payment, in units of the currency defined in `currency`. Response only.", "required": true }, { "name": "refunds", "type": [ { "type": "object", "fields": [ { "name": "data", "type": [ { "type": "unknown" } ] }, { "name": "has_more", "type": [ { "type": "unknown" } ] }, { "name": "total_count", "type": [ { "type": "unknown" } ] }, { "name": "url", "type": [ { "type": "unknown" } ] } ] } ], "description": "An object containing the following fields:\n\\* `data` - A list of up to three refunds.\n\\* `has_more` - Indicates whether there are more than three refunds against this payment.\n\\* `total_count` - Total number of refunds against this payment.\n\\* `url` - URL for requesting all of the refunds against this payment.\n\nResponse only.", "required": true }, { "name": "requested_currency", "description": "When `fixed_side` is **sell**, it is the currency received by the merchant. \nWhen `fixed_side` is **buy**, it is the currency charged to the buyer (customer) to pay the seller (merchant). \nThree-letter ISO 4217 code. Relevant to payments with FX.\nSee also `currency` and `fixed_side` fields.", "type": [ { "type": "string" } ], "required": true }, { "name": "show_intermediate_return_page", "type": [ { "type": "boolean" } ], "description": "The merchant's mobile app redirects the customer to a bank's web page for completion of the payment. When the payment is complete, the customer is redirected back to a **Payment Complete** page or **Error** page in the mobile app. If the bank does not support URL redirection, set this field to **true** and Rapyd will send the bank an intermediate URL. After the payment is complete, Rapyd's intermediate URL redirects the consumer back to the mobile app. Default is **false**.", "required": true }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "payment_" } ], "description": "The ID of the payment created before the first payment you want to retrieve. String starting with **payment_**.\n\nRelevant to [List Payments](ref:list-payments).", "required": true }, { "type": [ { "type": "string" } ], "name": "statement_descriptor", "description": "A text description suitable for a customer's payment statement. Limited to 22 characters.", "required": true }, { "name": "status", "type": [ { "type": "string", "possibleValues": [ "ACT", "CAN", "CLO", "ERR", "EXP", "NEW", "REV" ] } ], "description": "Indicates the status of the payment. Response only.\n\n**Responses:**\nOne of the following:\n\\* **ACT** - Active and awaiting payment. Can be updated.\n\\* **CAN** - Canceled by the merchant or the customer's bank.\n\\* **CLO** - Closed and paid.\n\\* **ERR** - Error. An attempt was made to create or complete a payment, but it failed.\n\\* **EXP** - The payment has expired.\n\\* **NEW** - Not closed.\n\\* **REV** - Reversed by Rapyd. See `cancel_reason`, above.", "required": true }, { "name": "textual_codes", "type": [ { "type": "object", "fields": [ { "name": "code", "type": [ { "type": "unknown" } ] }, { "name": "pay_code", "type": [ { "type": "unknown" } ] }, { "name": "pairing_code", "type": [ { "type": "unknown" } ] }, { "name": "payment_code", "type": [ { "type": "unknown" } ] }, { "name": "response_code", "type": [ { "type": "unknown" } ] } ] } ], "description": "A set of text codes for the customer to use to complete the steps described in the `instructions` field. Response only.\n\nContains one or more of the following fields:\n\\* `code`\n\\* `pay_code` \n\\* `pairing_code` \n\\* `payment_code` \n\\* `response_code`", "required": true }, { "name": "token", "type": [ { "type": "string", "startsWith": "payment_" } ], "description": "ID of the payment to complete. String starting with **payment_**. Relevant to the [Complete Payment](ref:complete-payment) method.", "required": true }, { "name": "transaction_id", "type": [ { "type": "string" } ], "description": "ID of the associated transaction. Response only.", "required": true }, { "name": "visual_codes", "type": [ { "type": "object" } ], "description": "A set of images for the customer to use to complete the steps described in the `instructions` field. For example, a QR code or barcode. Response only.", "required": true }, { "name": "wallets", "type": [ { "type": "array" } ], "description": "Array of objects that represent the wallets that the funds are paid into. See [Wallets Array](ref:wallets-array).", "required": true } ] }, { "product": "collect", "id": "payment-fees-object", "type": "type", "name": "PaymentFees", "description": "The Payment Fees object defines transaction fees and foreign exchange fees that the client can define for its customers. These fees are added to the payment amount. The client can use this feature to pass Rapyd's fees through to the customer.", "fields": [ { "name": "transaction_fee", "type": [ { "type": "object" } ], "description": "Describes the fee for processing the transaction. See ***Transaction Fee Object***, below.", "required": true }, { "name": "fx_fee", "type": [ { "type": "object" } ], "description": "Describes the fees for processing the currency exchange. Relevant to payments with FX.\n See ***FX Fee Object***, below.", "required": true }, { "name": "gross_fees", "type": [ { "type": "number" } ], "description": "The total gross fees for the transaction, in units defined by `currency_code`. Relevant to responses.", "required": true }, { "name": "net_fees", "type": [ { "type": "number" } ], "description": "The total net fees for the transaction, in units defined by `merchant_requested_currency`. Relevant to responses.", "required": true } ] }, { "product": "collect", "id": "outcome-object", "type": "type", "name": "Outcome", "description": "", "fields": [ { "name": "network_status", "type": [ { "type": "string", "possibleValues": [ "approved_by_network", "declined_by_network", "not_sent_to_network", "reversed_after_approval" ] } ], "description": "Network status of the payment. One of the following: \n* **approved_by_network**\n* **declined_by_network**\n* **not_sent_to_network**\n* **reversed_after_approval**", "required": true }, { "name": "risk_level", "type": [ { "type": "string", "possibleValues": [ "normal", "elevated", "highest", "not_assessed" ] } ], "description": "Assessment of the risk level of the payment. One of the following: \n* **normal**\n* **elevated**\n* **highest**\n* **not_assessed**", "required": true }, { "name": "seller_message", "type": [ { "type": "string" } ], "description": "Message to the merchant.", "required": true }, { "name": "type", "description": "Indicates the outcome of the risk assessment. One of the following:\n* **authorized**\n* **manual_review**\n* **issuer_declined**\n* **blocked**\n* **invalid**", "type": [ { "type": "string", "possibleValues": [ "authorized", "manual_review", "issuer_declined", "blocked", "invalid" ] } ], "required": true }, { "name": "reason", "type": [ { "type": "string", "possibleValues": [ "highest_risk_level", "elevated_risk_level", "rule" ] } ], "description": "More detailed indication of the reason indicated by `type`. One of the following:\n* **highest_risk_level** - Blocked by default rules.\n* **elevated_risk_level** - Placed in review by default rules.\n* **rule** - Placed in review by customer-designed rules.", "required": true } ] }, { "product": "collect", "parent": "payment-object", "id": "create-payment", "type": "request", "name": "CreatePaymentRequest", "description": "Use the POST method to create a payment. Use this method in the following situations:\n\n* To collect money immediately for a one-time charge.\n* To fund one or more Rapyd Wallets.\n* To start the collection process in the middle of a billing cycle. Relevant to subscriptions.\n* To replace a failed payment in a group payment. You can replace all or part of the portion that failed.\n\nIf the `payment_method` is not specified, Rapyd collects the funds from the `default_payment_method` of the Customer object.\n\nThis method triggers the **Payment Succeeded** webhook. This webhook contains the same information as the response. If the action of a third party is not required, the **Payment Completed** webhook is also triggered.\n\nThe following asynchronous webhooks provide information about later changes to the Payment object:\n* [Webhook - Payment Completed](ref:webhook-payment-completed) \n* [Webhook - Payment Failed](ref:webhook-payment-failed) \n* [Webhook - Payment Expired](ref:webhook-payment-expired) \n* [Webhook - Escrow Released](ref:webhook-escrow-released)\n\nIn the sandbox, to complete simulation of a payment method that requires the action of a third party, you must run [Complete Payment](ref:complete-payment).\n \n**Notes:** \n* Only clients with [PCI](ref:glossary) certification can handle personal identifying information for cards. Clients that are not PCI-certified can use Rapyd Checkout to collect money from a card. See [Rapyd Checkout Overview](doc:rapyd-checkout-overview).\n* If you create a payment that is split by amount and the total of the identified wallets is less than the amount of the payment, the remainder is paid into the client wallet.\n* If you are using this method in the sandbox and are directed to the simulated 3DS authentication page, your `code` is any number.\n\n**Prerequisites**\n* Customer - Required for using a customer's default payment method on file. See [Create Customer](ref:create-customer).\n* Payment Method - Required for using a payment method on file. See [Add Payment Method to Customer](ref:add-payment-method-to-customer) and [Tokens](ref:tokens).\n* Wallet - Required for directing the collected funds to a merchant or customer. See [Create Wallet](ref:create-wallet).", "method": "POST", "path": "/v1/payments", "params": [], "body": [ { "name": "address", "type": [ { "type": "object" } ], "required": false, "description": "Billing address associated with this specific payment. 'address' object." }, { "name": "amount", "type": [ { "type": "number" } ], "required": true, "description": "The amount of the payment, in units of the currency defined in `currency`. Decimal." }, { "name": "capture", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines when the payment is processed for capture. When **true**, the payment is captured immediately. When **false**, the payment is captured at a later time. Relevant to cards. Default is **true**." }, { "name": "complete_payment_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected after a successful payment. Required for bank redirect payment methods." }, { "name": "currency", "type": [ { "type": "string" } ], "required": true, "description": "Defines the currency for the amount. Three-letter ISO 4217 code. In FX transactions, see full explanations on `currency`, `fixed_side` and `requested_currency` fields in [Payment Object](ref:payment-object)." }, { "name": "customer", "type": [ { "type": "string", "startsWith": "cus_" } ], "required": false, "description": "ID of the customer. String starting with **cus_**. Required if `payment_method` is blank." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the payment." }, { "name": "error_payment_url", "type": [ { "type": "string" } ], "required": false, "description": "URL where the customer is redirected in case of an error in the payment. Required for bank redirect payment methods." }, { "name": "escrow", "type": [ { "type": "boolean" } ], "required": false, "description": "Determines whether the payment is held in escrow for later release. Relevant for card payments." }, { "name": "escrow_release_days", "type": [ { "type": "number" } ], "required": false, "description": "Defines the number of days after the creation of the payment that the funds are automatically released. Relevant when `escrow` is **true**." }, { "name": "ewallets", "type": [ { "type": "array", "arrayTypes": [ { "type": "object" } ] } ], "required": false, "description": "Represents the wallets that the money is paid into. Array of objects." }, { "name": "expiration", "type": [ { "type": "number" } ], "required": false, "description": "End of the time allowed for customer to make this payment, in [*Unix time*](ref:glossary). Must be after the current time." }, { "name": "fixed_side", "type": [ { "type": "string" } ], "required": false, "description": "Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). See [Payment Object](ref:payment-object) for full explanation." }, { "name": "initiation_type", "type": [ { "type": "string" } ], "required": false, "description": "Describes how the transaction was initiated. One of the following: **customer_present**, **installment**, **moto**, **recurring**, **unscheduled**." }, { "name": "group_payment", "type": [ { "type": "string" } ], "required": false, "description": "ID of the group payment, a string starting with 'gp_'. Relevant to replacing a payment that failed." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "ID defined by the client." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "payment_fees", "type": [ { "type": "object" } ], "required": false, "description": "Object that defines transaction fees and foreign exchange fees. These are fees that the Rapyd merchant can define for its consumers in addition to the payment amount." }, { "name": "payment_method", "type": [ { "type": "string" } ], "required": true, "description": "Payment Method object or ID. See [Payment Method Type Object](ref:payment-method-type-object)." }, { "name": "payment_method_options", "type": [ { "type": "object" } ], "required": false, "description": "Object describing additional information required for the payment. The object is returned by [Get Payment Method Required Fields](ref:get-payment-method-required-fields)." }, { "name": "receipt_email", "type": [ { "type": "string" } ], "required": false, "description": "Email address that the receipt for this transaction is sent to." }, { "name": "requested_currency", "type": [ { "type": "string" } ], "required": false, "description": "When `fixed_side` is **sell**, it is the currency received by the merchant. When `fixed_side` is **buy**, it is the currency charged to the buyer (customer) to pay the seller (merchant). Three-letter ISO 4217 code." }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "A text description that appears in the customer's bank statement. Limited to 22 characters." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-object", "id": "update-payment", "type": "request", "name": "UpdatePaymentRequest", "description": "Use the POST method to change or modify a payment when the status of the payment is **ACT** (active). You can update additional fields if they are listed under `payment_options` in the response from [Get Payment Method Required Fields](ref:get-payment-method-required-fields) and `is_updateable` is set to **true**.\n\nThis method triggers the **Payment Updated** webhook. This webhook contains the same information as the response.", "method": "POST", "path": "/v1/payments/{payment}", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." } ], "body": [ { "name": "address", "type": [ { "type": "object" } ], "required": false, "description": "Billing address associated with this specific payment. 'address' object." }, { "name": "description", "type": [ { "type": "string" } ], "required": false, "description": "Description of the payment." }, { "name": "escrow", "type": [ { "type": "boolean" } ], "required": false, "description": "To release escrow funds immediately, set to **false**. If there are multiple sellers, the funds are released to all of them. Relevant to card payments with escrow." }, { "name": "escrow_release_days", "type": [ { "type": "number" } ], "required": false, "description": "Defines the number of days after the creation of the payment that the funds are automatically released. Relevant when `escrow` is **true**." }, { "name": "initiation_type", "type": [ { "type": "string" } ], "required": false, "description": "Category of transaction initiation type." }, { "name": "metadata", "type": [ { "type": "object" } ], "required": false, "description": "A JSON object defined by the client." }, { "name": "receipt_email", "type": [ { "type": "string" } ], "required": false, "description": "Email address that the receipt for this transaction is sent to." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-object", "id": "capture-payment", "type": "request", "name": "CapturePaymentRequest", "description": "Use the POST method to capture a payment. Use this method to capture some or all of a card payment that was previously authorized with [Create Payment](ref:create-payment) with `capture` set to **false**. \n\nNotes: \n >* The captured amount cannot exceed the payment amount.\n >* You cannot capture a payment that was previously captured.\n >* If a payment is not captured within seven days after it is created, the payment expires.\n >* An expired payment cannot be captured.\n\nThis method triggers the **Payment Captured** webhook. This webhook contains the same information as the response. See [Webhook - Payment Captured](ref:webhook-payment-captured)", "method": "POST", "path": "/v1/payments/{payment}/capture", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." } ], "body": [ { "name": "amount", "type": [ { "type": "number" } ], "required": false, "description": "The amount of the payment. Decimal. If this parameter is omitted, the entire remaining amount of the 'payment' object is paid." }, { "name": "receipt_email", "type": [ { "type": "string" } ], "required": false, "description": "Email address that the receipt for this transaction is sent to." }, { "name": "statement_descriptor", "type": [ { "type": "string" } ], "required": false, "description": "A text description that appears in the customer's bank statement. Limited to 22 characters." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-object", "id": "complete-payment", "type": "request", "name": "CompletePaymentRequest", "description": "Use the POST method in the sandbox to simulate a completion of a payment that has `status` = **ACT** (active). This method changes the status to **CLO** (closed). \n\nThis method is relevant for the following payment method types:\n\\* **cash**, **bank_redirect**, **bank_transfer**, or **ewallet** - Where the action of a third-party completes the transaction.\n\nFor a card payment, do the following:\n\\* Capture after authorization only - Use [Capture Payment](ref:capture-payment).\n\\* Simulate 3DS verification - In the simulated 3DS authentication window, enter **rapyd** for the username and **success** for the password.\n\nThis method triggers the **PAYMENT_COMPLETED** webhook. This webhook contains the same information as the response. See [Webhook - Payment Completed](ref:webhook-payment-completed).\n\n**Prerequisites:**\n \\* [Create Payment](ref:create-payment)", "method": "POST", "path": "/v1/payments/completePayment", "params": [], "body": [ { "name": "token", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment to complete. String starting with **payment_**." }, { "name": "param1", "type": [ { "type": "string" } ], "required": false, "description": "Depends on the type of payment method. See ***Body Parameters***, below." }, { "name": "param2", "type": [ { "type": "string" } ], "required": false, "description": "Depends on the type of payment method. See ***Body Parameters***, below." } ], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-object", "id": "retrieve-payment", "type": "request", "name": "RetrievePaymentRequest", "description": "Use the GET method to retrieve details of a payment.", "method": "GET", "path": "/v1/payments/{payment}", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-object", "id": "cancel-payment", "type": "request", "name": "CancelPaymentRequest", "description": "Use the DELETE method to cancel a payment where the `status` of the payment is **ACT**. Relevant to payment methods where `is_cancelable` = **true** in the response to [List Payment Methods by Country](ref:retrieve-all-payment-methods-by-country).\n\nThis method triggers the **Payment Canceled** webhook. This webhook contains the same information as the response.\n\n**NOTE:** If the `status` is **CLO**, use the [Create Refund](ref:create-refund) method.", "method": "DELETE", "path": "/v1/payments/{payment}", "params": [ { "name": "payment", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": true, "description": "ID of the payment. String starting with **payment_**." } ], "body": [], "headers": [], "query": [] }, { "product": "collect", "parent": "payment-object", "id": "list-payments", "type": "request", "name": "ListPaymentsRequest", "description": "Use the GET method to retrieve a list of all payments that you have created.", "method": "GET", "path": "/v1/payments", "params": [], "body": [], "headers": [], "query": [ { "name": "customer", "type": [ { "type": "string" } ], "required": false, "description": "Filters the list for payments related to the specified customer." }, { "name": "ending_before", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": false, "description": "The ID of the payment created after the last payment you want to retrieve. String starting with **payment_**." }, { "name": "ewallet", "type": [ { "type": "string" } ], "required": false, "description": "Filters the list for payments related to the specified wallet." }, { "name": "group", "type": [ { "type": "boolean" } ], "required": false, "description": "When **true**, includes only group payments in the response. When **false**, excludes group payments from the response. Default is **false**." }, { "name": "invoice", "type": [ { "type": "string" } ], "required": false, "description": "Filters the list for payments related to the specified invoice." }, { "name": "limit", "type": [ { "type": "string" } ], "required": false, "description": "The maximum number of payments to return. Range: 1-100. Default is 10." }, { "name": "merchant_reference_id", "type": [ { "type": "string" } ], "required": false, "description": "Merchant-defined ID." }, { "name": "order", "type": [ { "type": "string" } ], "required": false, "description": "Filters the list for payments related to the specified order." }, { "name": "payment_method", "type": [ { "type": "string" } ], "required": false, "description": "Filters the list for payments related to the specified payment method." }, { "name": "starting_after", "type": [ { "type": "string", "startsWith": "payment_" } ], "required": false, "description": "The ID of the payment created before the first payment you want to retrieve. String starting with **payment_**." }, { "name": "subscription", "type": [ { "type": "string" } ], "required": false, "description": "Filters the list for payments related to the specified subscription." } ] }, { "product": "collect", "parent": "payment-object", "id": "payment-errors", "type": "enum", "name": "PaymentError", "values": [ { "name": "ERROR_3DS_AUTHENTICATION_FAILURE", "description": "The request tried to create a payment with a card that requires 3DS authentication, but the authentication failed. The request was rejected. Corrective action: Try the request again. If the error persists, assess the security risk." }, { "name": "ERROR_3DS_VERIFICATION_IS_NOT_SUPPORTED", "description": "The request tried to create a payment that requires 3DS verification, but the specified payment method does not support 3DS verification. The request was rejected. Corrective action: Omit the '3d_required' field under 'payment_method_options', change the value of the '3d_required' payment method option to false, or use a payment method that supports 3DS verification." }, { "name": "ERROR_AUTH_ONLY_IS_NOT_SUPPORTED", "description": "The request tried to create a card authorization, but authorization without capture is not supported for the selected payment method type. The request was rejected. Corrective action: Use a payment method type that supports authorization-only transactions." }, { "name": "ERROR_CANCEL_PAYMENT", "description": "The request tried to cancel a payment, but the operation failed. Corrective action: Check all input fields, and verify that the payment exists and was not already closed." }, { "name": "ERROR_CAPTURE_PAYMENT", "description": "The request tried to capture a payment, but the payment could not be found or there was an error in the input parameters. The request was rejected. Corrective action: Determine whether the payment was closed, and check all input parameters." }, { "name": "ERROR_CAPTURE_PAYMENT_AMOUNT_EXCEEDS_AUTHORIZATION_AMOUNT", "description": "The request tried to capture a payment for an amount that exceeds the amount in the original authorization transaction. The request was rejected. Corrective action: Set ‘amount’ less than or equal to the original authorization amount." }, { "name": "ERROR_CARD_PAYMENT_WITHOUT_CAPTURE_NOT_SUPPORTED", "description": "The request tried to make a card payment with authorization only, but the selected payment method does not support it. The request was rejected. Corrective action: Set 'capture' to 'true' or use a different payment method." }, { "name": "ERROR_CARD_VALIDATION_CAPTURE_TRUE", "description": "The request attempted to validate a card, but the request also attempted to capture a payment. The request was rejected. Corrective action: Create a payment with a card payment method, set 'capture' to false, and set 'amount’ to 0." }, { "name": "ERROR_CARD_VALIDATION_IN_GROUP_PAYMENT", "description": "The request attempted to validate a card as part of a group payment. The request was rejected. Corrective action: Create a payment with a card payment method, set ‘capture' to false, set 'amount’ to 0, and list only one payment in the 'payments' array." }, { "name": "ERROR_CARD_VALIDATION_IN_PAYMENT_WITH_ESCROW", "description": "The request attempted to validate a card as part of an escrow transaction. The request was rejected. Corrective action: Create a payment with a card payment method, set 'capture' to false, set 'amount’ to 0, and set 'escrow' to null." }, { "name": "ERROR_CARD_VALIDATION_IN_PAYMENT_WITH_FX", "description": "The request attempted to validate a card, but the request also attempted to exchange currency. The request was rejected. Corrective action: Create a payment with a card payment method, set 'capture' to false, set 'amount’ to 0, and set 'requested_currency' to null." }, { "name": "ERROR_CARD_VALIDATION_IN_SPLIT_PAYMENT", "description": "The request attempted to validate a card as part of a split payment. The request was rejected. Corrective action: Create a payment with a card payment method, set 'capture' to false, set 'amount’ to 0, and list only one wallet in the 'ewallets' array." }, { "name": "ERROR_CREATE_PAYMENT", "description": "The request tried to create a payment, but the payment method was not found. The request was rejected. Corrective action: Use the ID of the payment method in the 'payment_method' field. Alternatively, if the customer has a default payment method, you can use the ID of the customer in the 'customer' field." }, { "name": "ERROR_CREATE_PAYMENT_AMOUNT_EXCEEDS_MAXIMUM", "description": "The request tried to create a payment, but the amount was larger than what is allowed by the payment method. The request was rejected. Corrective action: Set 'amount' so that the amount is less than the 'max_amount' allowed for the currency in the payment method, as shown in the response to 'List Payment Methods by Country'." }, { "name": "ERROR_CREATE_PAYMENT_AMOUNT_LESS_THAN_MINIMUM", "description": "The request tried to create a payment, but the amount was smaller than what is allowed by the payment method. The request was rejected. Corrective action: Set 'amount' so that the amount is greater than the 'min_amount' allowed for the currency in the payment method, as shown in the response to 'List Payment Methods by Country'." }, { "name": "ERROR_CREATE_PAYMENT_CAPTURE_FOR_CARD_METHODS_ONLY", "description": "The request tried to create a payment, but the 'category' of the payment method was not 'card' and 'capture' was set. For all non-card payment methods, 'capture' must be null. The request was rejected. Corrective action: Use a card payment method or set 'capture' to null." }, { "name": "ERROR_CREATE_PAYMENT_CAPTURE_NOT_VALID", "description": "The request tried to create a payment, but the method of capture could not be determined. The request was rejected. Corrective action: Set 'capture' to true or false." }, { "name": "ERROR_CREATE_PAYMENT_COMPLETE_PAYMENT_URL_NOT_VALID", "description": "The request tried to create a payment, but the complete payment URL was missing or not recognized. The request was rejected. Corrective action: Use a valid URL for 'complete_payment_url." }, { "name": "ERROR_CREATE_PAYMENT_CURRENCY_NOT_SUPPORTED", "description": "The request tried to create a payment, but the currency was not recognized or not supported by the payment method provided. The request was rejected. Corrective action: Choose a currency that is supported by the payment method, or choose a payment method that supports the currency." }, { "name": "ERROR_CREATE_PAYMENT_ERROR_PAYMENT_URL_NOT_VALID", "description": "The request tried to create a payment, but the error payment URL was missing or not recognized. The request was rejected. Corrective action: Use a valid URL for 'error_payment_url'." }, { "name": "ERROR_CREATE_PAYMENT_INSUFFICIENT_FUNDS", "description": "The request tried to create a payment, but there were insufficient funds for the transaction. The request was rejected. Corrective action: None. Contact the customer." }, { "name": "ERROR_CREATE_PAYMENT_PERCENTAGE_MUST_BE_BETWEEN_0_AND_100", "description": "The request tried to split a payment among several wallets according to percentage, but the percentage was out of range. The request was rejected. Corrective action: Set 'percentage' to a decimal number between 0 and 100, with up to 4 decimal places." }, { "name": "ERROR_CREATE_PAYMENT_SPLIT_MISSING_AMOUNT_OR_PERCENTAGE", "description": "The request tried to create a payment split among two or more wallets, but the allocation of funds was not recognized. The request was rejected. Corrective action: In the 'ewallets' array, indicate a 'percentage' for all wallets or an 'amount' for all wallets." }, { "name": "ERROR_FEES_ONLY_ALLOWED_FOR_EWALLET_TRANSACTIONS", "description": "The request tried to make a payment, but it also tried to set a fee and the payment was not to a wallet. The request was rejected. Corrective action: For a payment that is not to a wallet, leave 'payment_fees' unset." }, { "name": "ERROR_FX_FEE_ONLY_ALLOWED_FOR_FX_TRANSACTIONS", "description": "The request tried to create a payment, but it also tried to set a foreign exchange fee and the payment was not a foreign exchange transaction. The request was rejected. Corrective action: For a payment that does not require foreign exchange, leave 'fx_fee' unset." }, { "name": "ERROR_GET_AMOUNT_AND_PERCENTAGE", "description": "The request tried to create a split payment, but the split was specified by both amount and percentage. The request was rejected. Corrective action: In the 'ewallets' array, indicate a 'percentage' for all wallets or an 'amount' for all wallets." }, { "name": "ERROR_GET_PAYMENT", "description": "The request tried to retrieve a payment, but the payment was not found. The request was rejected. Corrective action: Use a valid payment ID." }, { "name": "ERROR_INVALID_FX_FEE_CALC_TYPE", "description": "The request tried to create a payment, but the method of calculating the FX fee was missing or incorrect. The request was rejected. Corrective action: In the 'fx_fee' object, set 'calc_type' to 'gross' or 'net'." }, { "name": "ERROR_INVALID_FX_FEE_VALUE", "description": "The request tried to create a payment, but the FX fee was equal to or larger than the amount of the payment. The request was rejected. Corrective action: In the 'fx_fee' object, set 'value' to a decimal number greater than 0 and less than 100." }, { "name": "ERROR_INVALID_NET_FEES", "description": "The request tried to create a payment, but the total net fee was equal to or larger than the amount of the payment. The request was rejected. Corrective action: Set the transaction fee and the FX fee so that the total net fee is less than the amount of the payment." }, { "name": "ERROR_INVALID_TRANSACTION_FEE_CALC_TYPE", "description": "The request tried to create a payment, but the method of calculating the transaction fee was missing or incorrect. The request was rejected. Corrective action: In the 'transaction_fee' object, set 'calc_type' to 'gross' or 'net'." }, { "name": "ERROR_INVALID_TRANSACTION_FEE_FEE_TYPE", "description": "The request tried to create a payment, but the fee type of the transaction fee was missing or incorrect. The request was rejected. Corrective action: In the 'transaction_fee' object, set 'fee_type' to 'percentage' or 'absolute'." }, { "name": "ERROR_INVALID_TRANSACTION_FEE_VALUE", "description": "The request tried to create a payment, but the transaction fee was negative or was equal to or larger than the amount of the payment. The request was rejected. Corrective action: In the 'transaction_fee' object, set 'value' and 'fee_type' so that the fee is positive and less than the amount of the payment." }, { "name": "ERROR_MISSING_PAYMENT_TOKEN", "description": "The request attempted an operation that requires a payment ID, but the value was not found. The request was rejected. Corrective action: Use the ID of a valid payment." }, { "name": "ERROR_PAYMENT_AMOUNT_HAS_TO_BE_POSITIVE", "description": "The request tried to create a payment, but the 'amount' parameter of a wallet was not valid. The request was rejected. Corrective action: Set the 'amount' field for each wallet to a positive number." }, { "name": "ERROR_PAYMENT_CAN_NOT_BE_CANCELED", "description": "The request tried to cancel a payment, but the payment was already closed. The request was rejected. Corrective action: None. Determine why an attempt was made to cancel a closed payment." }, { "name": "ERROR_PAYMENT_EWALLET_NOT_AN_ARRAY_OR_STRING", "description": "The request tried to create a payment, but the ‘ewallet' parameter was not valid. The request was rejected. Corrective action: To indicate a payment to one wallet, set the 'ewallet' parameter to the ID of the wallet, which is a string starting with 'ewallet_’. To indicate a payment to several wallets, set the 'ewallet' parameter to an array of objects." }, { "name": "ERROR_PAYMENT_FIELD_NAME_NOT_KNOWN", "description": "The request attempted an operation that requires the names of fields in the Payment object, but one of the field names was unknown. The request was rejected. Corrective action: In the 'payment_fields' object, use the names of fields that exist in the Payment object." }, { "name": "ERROR_PAYMENT_FX_INVALID_EXPIRATION", "description": "The request tried to make a payment together with currency exchange, but the payment method requires an expiration date, and no valid expiration was found in the request. The request was rejected. Corrective action: Provide a valid value for 'expiration'." }, { "name": "ERROR_PAYMENT_INVALID_AMOUNT", "description": "The request tried to create a payment, but the amount was not found or not recognized. The request was rejected. Corrective action: Set 'amount' to a positive decimal number." }, { "name": "ERROR_PAYMENT_METHOD_TYPE_DOES_NOT_SUPPORT_FX", "description": "The request tried to make a payment together with currency exchange, but the payment method does not support currency exchange. The request was rejected. Corrective action: Use a different payment method." }, { "name": "ERROR_PAYMENT_METHOD_TYPE_DOES_NOT_SUPPORT_PAYMENT_CANCELLATION", "description": "The request tried to cancel a payment, but the payment type cannot be canceled. The request was rejected. Corrective action: Use 'Create Refund'." }, { "name": "ERROR_PAYMENT_METHODS_GET", "description": "The request attempted an operation that requires a payment method ID, but the payment method was not associated with the customer specified in the request. The request was rejected. Corrective action: Use a payment method that is associated with the specified customer." }, { "name": "ERROR_PAYMENT_MORE_THAN_TWO_AMOUNT_OR_PERCENTAGE_ARE_MISSING", "description": "The request tried to create a payment split among two or more wallets, but the allocation of funds was not recognized. The request was rejected. Corrective action: In the 'ewallets' array, indicate a 'percentage' for all wallets or an 'amount' for all wallets." }, { "name": "ERROR_PAYMENT_NOT_FOUND", "description": "The request attempted an operation that requires a payment ID, but the payment was not found. The request was rejected. Corrective action: Provide a valid payment ID." }, { "name": "ERROR_PAYMENT_NUMBER_OF_EWALLETS_EXCEEDED", "description": "The request tried to split a payment among several wallets, but there were too many wallets to process. The request was rejected. Corrective action: Split the payment among no more than 10 wallets." }, { "name": "ERROR_PAYMENT_PERCENT_MUST_BE_BETWEEN_0_TO_100", "description": "The request tried to split a payment among several eWallets according to percentage, but the 'percentage' was out of range. The request was rejected. Corrective action: Set 'percentage' as a decimal number between 0 and 100, with up to 4 decimal places." }, { "name": "ERROR_PAYMENT_PERCENTAGE_HAS_TO_BE_POSITIVE", "description": "The request tried to create a payment, but the 'percentage' parameter of a wallet was not valid. The request was rejected. Corrective action: For each wallet, set the 'percentage' field to a positive decimal number between 0 and 100, with up to 4 decimal places." }, { "name": "ERROR_PAYMENT_SPLIT_AMOUNT_EXCEEDS_PAYMENT_AMOUNT", "description": "The request tried to split a payment among several wallets, but the combined wallet amounts exceed the total amount of the payment. The request was rejected. Corrective action: Set the 'amount' of the payment to be the same as the total amount of transfers to all wallets." }, { "name": "ERROR_PAYMENT_SPLIT_EXCEEDED_MAXIMUM_NUMBER_OF_EWALLETS", "description": "The request tried to split a payment, but there were too many wallets in the request. The request was rejected. Corrective action: In the 'ewallets' array, specify no more than 10 wallets." }, { "name": "ERROR_SPLIT_PAYMENT_DUPLICATE_EWALLET", "description": "The request tried to split a payment between two or more wallets, but one wallet appeared more than once in the request. The request was rejected. Corrective action: Combine all payments to one wallet into a single entry in the 'ewallets' list." }, { "name": "ERROR_TRANSACTION_FEE_INVALID_AMOUNT", "description": "The request tried to create a payment, but the amount of the transaction fee was incorrect. The request was rejected. Corrective action: In the 'transaction_fee' object, set 'value' to a positive decimal number." }, { "name": "ERROR_UPDATE_PAYMENT", "description": "The request tried to update a payment, but the status of the payment does not allow updates. The request was rejected. Corrective action: None. Determine why an attempt was made to change the payment when the 'status' was not 'ACT'." }, { "name": "ERROR_USING_TOKEN", "description": "The request tried to update a payment, but the payment method could not be found, or the payment failed. The request was rejected. Corrective action: Check all input fields, and verify that the payment method exists." }, { "name": "IDEMPOTENCY_ERROR", "description": "The request tried to create a payment, but the 'idempotency' header was identical to that of another request made earlier. The request was rejected. Corrective action. Set 'idempotency' to a unique value." }, { "name": "INVALID_COMPLETE_PAYMENT_URL", "description": "The request tried to create a payment, but the 'complete_payment_url' parameter was not valid. The request was rejected. Corrective action: Use the correct URL." }, { "name": "INVALID_ERROR_PAYMENT_URL", "description": "The request tried to create a payment, but the 'error_payment_url' parameter was not valid. The request was rejected. Corrective action: Use the correct URL." }, { "name": "INVALID_PAYMENT", "description": "The request attempted an operation that requires a payment ID, but the payment was not found. The request was rejected. Corrective action: Use the ID of a valid payment." }, { "name": "ERROR_INVALID_PAYMENT_INITIATION_TYPE", "description": "The request tried to create a payment, but the initiation type was not recognized. The request was rejected. Corrective action: Set 'initiation_type' to one of the following values: 'customer_present', 'installment', 'moto', 'recurring', 'unscheduled'." }, { "name": "MISSING_PAYMENT", "description": "The request attempted an operation that requires a payment ID, but the payment was not found. The request was rejected. Corrective action: Use the ID of a valid payment." }, { "name": "PAYMENT_CAPTURED_BEFORE", "description": "The request tried to capture a payment, but the payment was previously closed. The request was rejected. Corrective action: None. Determine why capture was attempted for a closed payment." }, { "name": "UNKNOWN_PAYMENT_METHOD_FIELDS", "description": "The request tried to create or update a payment, but one of the fields in the 'payment_method' object was not recognized. The request was rejected. Corrective action: In the 'payment_method' object, submit a 'fields' object with documented fields only." } ] }, { "product": "collect", "id": "payment-fees-object", "type": "type", "name": "PaymentFees", "description": "The Payment Fees object defines transaction fees and foreign exchange fees that the client can define for its customers. These fees are added to the payment amount. The client can use this feature to pass Rapyd's fees through to the customer.", "fields": [ { "name": "transaction_fee", "type": [ { "type": "object" } ], "description": "Describes the fee for processing the transaction. See ***Transaction Fee Object***, below.", "required": true }, { "name": "fx_fee", "type": [ { "type": "object" } ], "description": "Describes the fees for processing the currency exchange. Relevant to payments with FX.\n See ***FX Fee Object***, below.", "required": true }, { "name": "gross_fees", "type": [ { "type": "number" } ], "description": "The total gross fees for the transaction, in units defined by `currency_code`. Relevant to responses.", "required": true }, { "name": "net_fees", "type": [ { "type": "number" } ], "description": "The total net fees for the transaction, in units defined by `merchant_requested_currency`. Relevant to responses.", "required": true } ] }, { "product": "collect", "id": "outcome-object", "type": "type", "name": "Outcome", "description": "", "fields": [ { "name": "network_status", "type": [ { "type": "string", "possibleValues": [ "approved_by_network", "declined_by_network", "not_sent_to_network", "reversed_after_approval" ] } ], "description": "Network status of the payment. One of the following: \n* **approved_by_network**\n* **declined_by_network**\n* **not_sent_to_network**\n* **reversed_after_approval**", "required": true }, { "name": "risk_level", "type": [ { "type": "string", "possibleValues": [ "normal", "elevated", "highest", "not_assessed" ] } ], "description": "Assessment of the risk level of the payment. One of the following: \n* **normal**\n* **elevated**\n* **highest**\n* **not_assessed**", "required": true }, { "name": "seller_message", "type": [ { "type": "string" } ], "description": "Message to the merchant.", "required": true }, { "name": "type", "description": "Indicates the outcome of the risk assessment. One of the following:\n* **authorized**\n* **manual_review**\n* **issuer_declined**\n* **blocked**\n* **invalid**", "type": [ { "type": "string", "possibleValues": [ "authorized", "manual_review", "issuer_declined", "blocked", "invalid" ] } ], "required": true }, { "name": "reason", "type": [ { "type": "string", "possibleValues": [ "highest_risk_level", "elevated_risk_level", "rule" ] } ], "description": "More detailed indication of the reason indicated by `type`. One of the following:\n* **highest_risk_level** - Blocked by default rules.\n* **elevated_risk_level** - Placed in review by default rules.\n* **rule** - Placed in review by customer-designed rules.", "required": true } ] } ]