# Ryft Payment API Ryft provides a collection of APIs that you can use to accept and process payments + marketplace functionality (payouts). We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data. # Authentication When you sign up for an account, you are given a secret and public API key pair. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure. ## Public API key Public keys should only be used in JavaScript or native applications. This key is solely used to identify the partner making requests. Supply this key in the `Authorization` header. ## Secret API key Your secret key should always be supplied in the `Authorization` header. Make sure this key is stored securely on your backend and never surfaced client-side. # Rate Limiting We use rate limiting on a per-user basis to protect our APIs against abuse. Our Sandbox environment is limited to 5 requests per second. Our production environment is limited to 50 requests per second. We also allow a brief burst above this limit to accommodate a sudden increase in traffic. If you exceed the above quota then the API will respond with a 429 status code and you will need to retry the API call (we recommend implementing a retry policy with an exponential back-off). Version: 1.1.0 ## Servers Sandbox environmment ``` https://sandbox-api.ryftpay.com/v1 ``` Production environment ``` https://api.ryftpay.com/v1 ``` ## Security ### secretApiKeyAuth Type: apiKey In: header Name: Authorization ### publicApiKeyAuth Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Ryft Payment API](https://developer.ryftpay.com/_bundle/documentation/api/reference/openapi.yaml) ## Payments Process payments with Ryft: authorizations, voids, captures, refunds etc. ### Create a new payment session - [POST /payment-sessions](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessioncreate.md): The start of the payment flow. Call this request once the customer has proceeded to checkout. Payment Sessions will auto-expire after several days if you don't take payment via the attempt-payment endpoint. ### Retrieve payment sessions between timestamps - [GET /payment-sessions](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessiongetbetweentimestamps.md): This is used to fetch payment sessions within a timestamp range, paginated ### Retrieve a payment session by Id - [GET /payment-sessions/{paymentSessionId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessionget.md): This is used to fetch a payment session by its paymentSessionId ### Update a payment session by Id - [PATCH /payment-sessions/{paymentSessionId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessionupdate.md): This is used to update a payment session by its Id. Note that this can only be used prior to a successful payment. Once payment has been approved, you cannot update a PaymentSession. ### Initiate a payment attempt - [POST /payment-sessions/attempt-payment](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessionattemptpayment.md): This is used to supply the card you have collected from the customer to pay for this payment session. Only call this endpoint from your front-end once you have collected the customer's card details. If you want the lowest PCI burden we recommend using our embedded payment forms in place of this endpoint. This ensures Ryft store & transmit the card details securely from our servers rather than your own. Please contact your account manager if you want to opt for this. ### Continue taking payment after the initial attempt. - [POST /payment-sessions/continue-payment](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessioncontinuepayment.md): Submit additional data for payment sessions that require further action after using attempt-payment. Note that our SDKs handle this step automatically. ### List payment transaction(s) - [GET /payment-sessions/{paymentSessionId}/transactions](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessionlisttransactions.md): List the transaction(s) for a particular payment ### Retrieve a payment transaction - [GET /payment-sessions/{paymentSessionId}/transactions/{paymentTransactionId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessiongettransactionbyid.md): Retrieve the transaction for a particular payment ### Manually capture a payment session - [POST /payment-sessions/{paymentSessionId}/captures](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessioncapturebyid.md): Call this endpoint to capture funds you have previously authorized on a payment session. You can only call this endpoint when the payment session is in status Approved and its captureFlow value is Manual. ### Void a payment session - [POST /payment-sessions/{paymentSessionId}/voids](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessionvoidbyid.md): Call this endpoint to void a payment session currently awaiting manual capture. This will reverse the amount authorized on the payment and return it to the customer. If voided on the same-day, the transaction will not show up on the customer's card statement(s). You can only call this endpoint when the payment session is in status Approved and its captureFlow value is Manual. ### Refund a payment - [POST /payment-sessions/{paymentSessionId}/refunds](https://developer.ryftpay.com/documentation/api/reference/openapi/payments/paymentsessioncreaterefund.md): Use this endpoint to refund an already captured payment session. Unlike voids, which are typically completed in minutes, refunds can take several days to be cleared by the card schemes. ## Webhooks Create and manage webhooks. ### Signatures As an additional security measure, you can verify the integrity of any webhook event you receive by checking the signature we provide within the `Signature` header. To do this simply take the webhook endpoint secret and `HMAC-SHA256` the request body. If the signatures are not equal then you may want to discard the message. ### Retry Policy If your webhook URL begins to fail we will start our retry mechanism. For each failing event we immediately retry several times before then retrying with an increasing delay until we've exhausted the maximum number of attempts. Each retry happens after (0, 1, 5, 10, 10, 10 minutes) ### Create/Register a webhook endpoint - [POST /webhooks](https://developer.ryftpay.com/documentation/api/reference/openapi/webhooks/webhookcreate.md): Create/Register a webhook endpoint to start receiving events ### List your webhook endpoints - [GET /webhooks](https://developer.ryftpay.com/documentation/api/reference/openapi/webhooks/webhookslist.md): Returns a list of your webhook endpoints. They are returned in sorted (by epoch) order (default is newest first). ### Retrieve a webhook endpoint - [GET /webhooks/{webhookId}](https://developer.ryftpay.com/documentation/api/reference/openapi/webhooks/webhookgetbyid.md): This is used to fetch a webhook by its unique Id ### Update a webhook endpoint - [PATCH /webhooks/{webhookId}](https://developer.ryftpay.com/documentation/api/reference/openapi/webhooks/webhookupdatebyid.md): This is used to update a webhook by its unique Id ### Delete a webhook endpoint - [DELETE /webhooks/{webhookId}](https://developer.ryftpay.com/documentation/api/reference/openapi/webhooks/webhookdeletebyid.md): This is used to delete a webhook by its unique Id ## Events Events are persisted throughout the lifecycle of a payment/action as you use our API. We use events to notify you when something important happens in your account (or a linked sub account). The most commonly used event occurs when a payment is captured, in which case we persist a `PaymentSession.captured` event and then (optionally) send it to any webhooks you have registered that are listening for that event type. Note that if you are taking payments as a platform (for sub accounts), events are saved against the sub account `accountId`, but will be sent to any webhooks that your account has configured. ### Retrieves events in sorted (by epoch) order - [GET /events](https://developer.ryftpay.com/documentation/api/reference/openapi/events/eventgetlist.md): Retrieves a list of events. They are returned in sorted (by epoch) order (default is newest first). You can query one of your sub-account's events buy using the Account header. ### Retrieve an Event by Id - [GET /events/{eventId}](https://developer.ryftpay.com/documentation/api/reference/openapi/events/eventgetbyid.md): This is used to fetch an Event by its eventId ## Accounts Account registration for your sub accounts ### Create a new sub account - [POST /accounts](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/subaccountcreate.md): This is for registering new users onto your platform that will act as one of your 'sub' accounts ### Retrieve a sub account by Id - [GET /accounts/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/subaccountgetbyid.md): This is used to fetch details for one of your sub accounts. ### Update a sub account by Id - [PATCH /accounts/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/subaccountupdate.md): This is used to update the details of one of your sub accounts. This API can only be accessed for NonHosted sub accounts. ### Verify a 'Business' entity sub account - [POST /accounts/{id}/verify](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/subaccountverify.md): Once you have created all Persons and satisfied all the verification requirements for them and the Business, you submit these details for verification. This endpoint cannot be accessed for Individual sub accounts as this process is done automatically after satisfying the verification requirements. ### Create a manual payout for a sub account - [POST /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/payoutcreate.md): Used to create manual payouts for a specified sub account. This API can only be accessed for NonHosted sub accounts that are configured for manual payouts. Note that the following requirements must be met: - the payoutMethodId supplied must have status equal to Valid - amount must be greater than or equal to the minimum configured payout amount for the account (e.g. £100) - verification.status cannot be Required on the account - frozen must not be true on the account ### List payouts for a sub account - [GET /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/payoutslist.md): Used to fetch a paginated list of payouts for the given sub account ### Retrieve a a payout for a sub account by Id - [GET /accounts/{id}/payouts/{payoutId}](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/payoutgetbyid.md): This is used to fetch a payout by its unique Id ### Create a link for a sub account to authorize their account - [POST /accounts/authorize](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/subaccountauthorize.md): We recommend calling this endpoint first when you onboard your users to cater for those that may already have Ryft accounts. If the email supplied is not registered with Ryft then you should instead use our account-links API to register a new user. This API can only be accessed for Hosted sub accounts. ### Create a manual payout for a sub account - [POST /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/payouts/payoutcreate.md): Used to create manual payouts for a specified sub account. This API can only be accessed for NonHosted sub accounts that are configured for manual payouts. Note that the following requirements must be met: - the payoutMethodId supplied must have status equal to Valid - amount must be greater than or equal to the minimum configured payout amount for the account (e.g. £100) - verification.status cannot be Required on the account - frozen must not be true on the account ### List payouts for a sub account - [GET /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/payouts/payoutslist.md): Used to fetch a paginated list of payouts for the given sub account ### Retrieve a a payout for a sub account by Id - [GET /accounts/{id}/payouts/{payoutId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payouts/payoutgetbyid.md): This is used to fetch a payout by its unique Id ## Payouts A payout represents the transfer of money from Ryft to a connected payout method (bank account), i.e. when we send money you're owed. Typically this is automated. However, the payouts API allows you to explicitly create payouts for your sub accounts. Generally we'd recommend this if you are a marketplace who wants to control exactly when payouts should be sent out. ### Create a manual payout for a sub account - [POST /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/payoutcreate.md): Used to create manual payouts for a specified sub account. This API can only be accessed for NonHosted sub accounts that are configured for manual payouts. Note that the following requirements must be met: - the payoutMethodId supplied must have status equal to Valid - amount must be greater than or equal to the minimum configured payout amount for the account (e.g. £100) - verification.status cannot be Required on the account - frozen must not be true on the account ### List payouts for a sub account - [GET /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/payoutslist.md): Used to fetch a paginated list of payouts for the given sub account ### Retrieve a a payout for a sub account by Id - [GET /accounts/{id}/payouts/{payoutId}](https://developer.ryftpay.com/documentation/api/reference/openapi/accounts/payoutgetbyid.md): This is used to fetch a payout by its unique Id ### Create a manual payout for a sub account - [POST /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/payouts/payoutcreate.md): Used to create manual payouts for a specified sub account. This API can only be accessed for NonHosted sub accounts that are configured for manual payouts. Note that the following requirements must be met: - the payoutMethodId supplied must have status equal to Valid - amount must be greater than or equal to the minimum configured payout amount for the account (e.g. £100) - verification.status cannot be Required on the account - frozen must not be true on the account ### List payouts for a sub account - [GET /accounts/{id}/payouts](https://developer.ryftpay.com/documentation/api/reference/openapi/payouts/payoutslist.md): Used to fetch a paginated list of payouts for the given sub account ### Retrieve a a payout for a sub account by Id - [GET /accounts/{id}/payouts/{payoutId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payouts/payoutgetbyid.md): This is used to fetch a payout by its unique Id ## Persons The Persons API allows the creation and management of one or more persons for the purpose of verification for `Business` sub accounts. Recommended if you wish to implement verification programmatically for your sub accounts. This API cannot be accessed for `Individual` sub accounts. ### Creates a new person under the account, for verification of Businesses - [POST /accounts/{id}/persons](https://developer.ryftpay.com/documentation/api/reference/openapi/persons/personcreate.md): This is for creating persons under your or your sub accounts account, required for verification of businesses. The following limits apply: - Maximum of 9 persons - Maximum of 5 persons with a role of Director - Maximum of 4 persons with a role of UltimateBeneficialOwner - Maximum of 1 person with a role of BusinessContact ### Retrieves persons in sorted (by epoch) order - [GET /accounts/{id}/persons](https://developer.ryftpay.com/documentation/api/reference/openapi/persons/personlist.md): Retrieves a list of the persons you've created for one of your sub accounts They are returned in sorted (by epoch) order (default is newest first) ### Retrieve a person by Id - [GET /accounts/{id}/persons/{personId}](https://developer.ryftpay.com/documentation/api/reference/openapi/persons/persongetbyid.md): This is used to fetch a person by its unique Id ### Update a person by Id - [PATCH /accounts/{id}/persons/{personId}](https://developer.ryftpay.com/documentation/api/reference/openapi/persons/personupdatebyid.md): This is used to update an existing person ### Deletes a person by Id - [DELETE /accounts/{id}/persons/{personId}](https://developer.ryftpay.com/documentation/api/reference/openapi/persons/persondeletebyid.md): Deletes a person under the account. This will also delete any files currently attached to the person. Note that you can only delete a person if verification.status is NotRequired or Required ## Payout Methods The Payout Methods API allows the creation and management of payout methods for use when receiving payouts, e.g. bank accounts. Recommended if you wish to implement payouts programmatically for your sub accounts. ### Creates a new payout method for a sub account - [POST /accounts/{id}/payout-methods](https://developer.ryftpay.com/documentation/api/reference/openapi/payout-methods/payoutmethodcreate.md): This is for creating payout methods for one of your sub accounts, so they can receive payouts. You can only create 1 payout method per currency ### Retrieves payout methods in sorted (by epoch) order - [GET /accounts/{id}/payout-methods](https://developer.ryftpay.com/documentation/api/reference/openapi/payout-methods/payoutmethodslist.md): Retrieves a list of the payout methods you've created for one of your sub accounts They are returned in sorted (by epoch) order (default is newest first) ### Retrieve a payout method by Id - [GET /accounts/{id}/payout-methods/{payoutMethodId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payout-methods/payoutmethodget.md): This is used to fetch a payout method by its unique Id for one of your sub accounts ### Update a payout method by Id - [PATCH /accounts/{id}/payout-methods/{payoutMethodId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payout-methods/payoutmethodupdate.md): This is used to update an existing payout method for one of your sub accounts ### Delete a payout method - [DELETE /accounts/{id}/payout-methods/{payoutMethodId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payout-methods/payoutmethoddelete.md): This is used to delete a payout method by its unique Id for one of your sub accounts ## Transfers A Transfer represents the movement of money between Ryft accounts. This API allows platforms/marketplaces to transfer money from/to particular sub accounts, useful when: - you owe a sub account money from a particular transaction and want to explicitly send it after the fact - you want to recoup funds from a sub account, such as when dealing with disputes - you want to collect additional/new commission from the sub account ### Initiates a transfer of money between Ryft accounts - [POST /transfers](https://developer.ryftpay.com/documentation/api/reference/openapi/transfers/transfercreate.md): Used to initiate a transfer of money between Ryft accounts. ### Fetches a paginated list of your transfers - [GET /transfers](https://developer.ryftpay.com/documentation/api/reference/openapi/transfers/transferslist.md): Retrieves a list of the transfers you've requested. Returned in sorted (by epoch) order (default is newest first) ### Retrieve a transfer by Id - [GET /transfers/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/transfers/transfergetbyid.md): This is used to fetch a transfer by its unique Id ## Balances The balances API allows you to view your own or a particular sub accounts balances in real-time. Typically useful when making use of manual payouts or our transfers API so you can determine the funds available prior to initiating requests. ### List balances - [GET /balances](https://developer.ryftpay.com/documentation/api/reference/openapi/balances/balanceslist.md): Retrieves a list of balances for the given account ## Balance Transactions Allows you to query for balance transactions. These transactions represent all actions within a Ryft account that impact account balances. This API can only be used for reconciliation on transactions created from July 2025 onwards ### List balance transactions - [GET /balance-transactions](https://developer.ryftpay.com/documentation/api/reference/openapi/balance-transactions/balancetransactionslist.md): Retrieves a list of balance transactions for the given account. ## Account Links Generate temporary account link URLs to our portal for your sub accounts to register and configure their payout details. This API can only be accessed for `Hosted` sub accounts. ### Generate a new temporary account link - [POST /account-links](https://developer.ryftpay.com/documentation/api/reference/openapi/account-links/accountlinkscreate.md): Generate a temporary account link to redirect the user to, in order for them to complete registration and payout setup via our portal ## Platform Fees Query any platform fees that your account has taken (when taking payments on behalf of linked sub accounts) ### Retrieves your platform fees in sorted (by epoch) order - [GET /platform-fees](https://developer.ryftpay.com/documentation/api/reference/openapi/platform-fees/platformfeegetlist.md): Retrieves a list of the application fees you've collected. They are returned in sorted (by epoch) order (default is newest first) ### Retrieve a platform fee by Id - [GET /platform-fees/{platformFeeId}](https://developer.ryftpay.com/documentation/api/reference/openapi/platform-fees/platformfeegetbyid.md): This is used to fetch a platform fee by its platformFeeId ### Retrieve platform fee refund(s) - [GET /platform-fees/{platformFeeId}/refunds](https://developer.ryftpay.com/documentation/api/reference/openapi/platform-fees/platformfeegetrefunds.md): This is used to fetch a platform fee refunds by their platformFeeId ## Customers The Customers API allows you to persist customer details across sessions. You should use this if you wish to support saving a customer's payment methods and thereby enabling them to reuse previously entered details for future payments. ### Creates a new customer within your account - [POST /customers](https://developer.ryftpay.com/documentation/api/reference/openapi/customers/customercreate.md): This is for creating customers within your Ryft account (to enable features such as saved payment methods) ### List customers - [GET /customers](https://developer.ryftpay.com/documentation/api/reference/openapi/customers/customerslist.md): Used to fetch a paginated list of one or more Customers ### Retrieve a customer by Id - [GET /customers/{customerId}](https://developer.ryftpay.com/documentation/api/reference/openapi/customers/customergetbyid.md): This is used to fetch a customer by its unique Id ### Update a customer by Id - [PATCH /customers/{customerId}](https://developer.ryftpay.com/documentation/api/reference/openapi/customers/customerupdatebyid.md): This is used to update an existing customer ### Delete a customer (and all their payment methods) - [DELETE /customers/{customerId}](https://developer.ryftpay.com/documentation/api/reference/openapi/customers/customerdeletebyid.md): This is used to delete a customer by its unique Id ### Retrieve a customer's payment methods - [GET /customers/{customerId}/payment-methods](https://developer.ryftpay.com/documentation/api/reference/openapi/customers/customergetpaymentmethods.md): This is used to fetch a customer's payment methods ## Payment Methods The Payment Methods API allows you to tokenize and store previously used payment methods. ### Retrieve a payment method by Id - [GET /payment-methods/{paymentMethodId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payment-methods/paymentmethodgetbyid.md): This is used to fetch a payment method by its unique Id ### Update a payment method by Id - [PATCH /payment-methods/{paymentMethodId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payment-methods/paymentmethodupdatebyid.md): This is used to update an existing payment method ### Delete a payment method by Id - [DELETE /payment-methods/{paymentMethodId}](https://developer.ryftpay.com/documentation/api/reference/openapi/payment-methods/paymentmethoddeletebyid.md): This is used to delete a payment method by instead. Note that you can only delete payment-methods that aren't single-use. For example you can delete a customer's saved payment method, but you cannot delete a token generated for one-time purchases ## Subscriptions The subscriptions API allows you to automatically have Ryft schedule and charge recurring payments for a specific day and time. This API is not required to process recurring payments. After additional configuration, you can use our payment-sessions API to create and charge the recurring payments yourself. ### Creates a new subscription - [POST /subscriptions](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptioncreate.md): Use to create a Subscription (whereby Ryft manage the automatic scheduling and billing of a recurring payment series) ### List subscriptions - [GET /subscriptions](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptionslist.md): Used to fetch a paginated list of subscriptions ### Retrieve a subscription by Id - [GET /subscriptions/{subscriptionId}](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptiongetbyid.md): This is used to fetch a subscription by its unique Id ### Updates a subscription by Id - [PATCH /subscriptions/{subscriptionId}](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptionupdatebyid.md): Use to update a Subscription. Cannot be used if the Subscription is Cancelled or Ended. ### Pause a subscription by Id - [PATCH /subscriptions/{subscriptionId}/pause](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptionpausebyid.md): Used to schedule a pause for a Subscription. Only 'Active' subscriptions can be paused, though the details for already 'Paused' subscriptions can also be edited. The subscription will remain in 'Active' and will be moved to 'Paused' when it was next due to be billed. The reason or duration of the pause can be edited by calling this endpoint again, even after it has moved to 'Paused'. After a pause is scheduled but whilst still in 'Active', the pause can be unscheduled via the 'unschedule' flag. ### Resume a subscription by Id - [PATCH /subscriptions/{subscriptionId}/resume](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptionresumebyid.md): Use to resume a paused Subscription. ### Cancel a subscription by Id - [DELETE /subscriptions/{subscriptionId}/cancel](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptioncancelbyid.md): Cancel a subscription by its unique Id. This will immediately move the subscription to Cancelled and stop billing the customer. This state is terminal and cannot be reversed. ### Retrieve a list of the payments specific to a subscription - [GET /subscriptions/{subscriptionId}/payment-sessions](https://developer.ryftpay.com/documentation/api/reference/openapi/subscriptions/subscriptionslistpaymentsessions.md): Used to fetch a paginated list of the payment sessions making up the subscription ## Files The Files API allows you to query for and upload files to Ryft. Some files may be generated internally by Ryft when requesting reports, or alternatively you may have uploaded evidence/verification documents ### List files - [GET /files](https://developer.ryftpay.com/documentation/api/reference/openapi/files/fileslist.md): Used to fetch a paginated list of files under your account ### Create/Upload a new file to your account. - [POST /files](https://developer.ryftpay.com/documentation/api/reference/openapi/files/filecreate.md): Upload a file to Ryft via our API. Useful if you need to: - upload evidence when challenging disputes - upload KYB/KYC documents for sub accounts ### Retrieve a file - [GET /files/{fileId}](https://developer.ryftpay.com/documentation/api/reference/openapi/files/filegetbyid.md): Retrieve a file by its unique ID ## Apple Pay Allows implementation of Apple Pay on the web via the API with Ryft's Apple Pay processing certificate. ### Register a domain for Apple Pay - [POST /apple-pay/web-domains](https://developer.ryftpay.com/documentation/api/reference/openapi/apple-pay/applepaywebdomainregister.md): Registers a domain name for Apple Pay on the web. Note that this is required if relying on Ryft's Apple Pay processing certificate. A Maxiumum of 99 domains can be registered against a single Ryft account. Each domain must host our verification file under /.well-known/apple-developer-merchantid-domain-association. Important: the Content-Type of the hosted file must be application/octet-stream. ### List Apple Pay web domains - [GET /apple-pay/web-domains](https://developer.ryftpay.com/documentation/api/reference/openapi/apple-pay/applepaywebdomainslist.md): List the web domains you have registered for Apple Pay ### Retrieve an Apple Pay web domain - [GET /apple-pay/web-domains/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/apple-pay/applepaywebdomaingetbyid.md): This is used to fetch an Apple Pay web domain by its unique Id ### Delete an Apple Pay web domain - [DELETE /apple-pay/web-domains/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/apple-pay/applepaywebdomaindeletebyid.md): This is used to delete an Apple Pay web domain by its unique Id ### Create an Apple Pay web session - [POST /apple-pay/sessions](https://developer.ryftpay.com/documentation/api/reference/openapi/apple-pay/applepaycreatesession.md): Request a new Apple Pay web session. Use this endpoint if you process Apple Pay on the web and: - you want to rely on Ryft's Apple Pay processing certificate - have an existing integration or want to implement Apple Pay via our API (without using our SDKs) ## Disputes Disputes (also known as chargebacks) occur when a cardholder wants to query or challenge a transaction on their card statement. The Disputes API allows you to keep track of and manage disputes. ### List disputes - [GET /disputes](https://developer.ryftpay.com/documentation/api/reference/openapi/disputes/disputeslist.md): Used to fetch a paginated list of disputes ### Retrieve a dispute - [GET /disputes/{disputeId}](https://developer.ryftpay.com/documentation/api/reference/openapi/disputes/disputegetbyid.md): This is used to fetch a dispute by its unique Id ### Accept a dispute - [POST /disputes/{disputeId}/accept](https://developer.ryftpay.com/documentation/api/reference/openapi/disputes/disputeacceptbyid.md): Accepts a specific dispute by Id. Typically you should use this if the dispute is in fact legitimate and you are accepting the financial impact. Note that this operation cannot be done. ### Add evidence to a dispute - [PATCH /disputes/{disputeId}/evidence](https://developer.ryftpay.com/documentation/api/reference/openapi/disputes/disputeaddevidencebyid.md): Adds or updates the evidence currently attached to the dispute. Note that for file evidence, you must first upload the file via our files API. Once you have attached all relevant evidence, call the /challenge endpoint to submit the evidence for review. Note: the Dispute must be in status Open for this operation. ### Remove evidence from a dispute - [DELETE /disputes/{disputeId}/evidence](https://developer.ryftpay.com/documentation/api/reference/openapi/disputes/disputeremoveevidencebyid.md): Removes evidence currently attached to a dispute. Note: the Dispute must be in status Open for this operation. ### Challenge a dispute - [POST /disputes/{disputeId}/challenge](https://developer.ryftpay.com/documentation/api/reference/openapi/disputes/disputechallengebyid.md): Challenges a specific dispute. You should call this endpoint once you have attached all the relevant evidence. Note that you can no longer submit further evidence once challenged, so make sure you have gathered as much as possible to ensure a better chance of winning the dispute. ## In-Person Products The in-person products API allows you query for the products we offer for in-person payments. Useful to view and decide which SKUs you wish to order. Note that products themselves cannot be ordered. You must select one or more SKUs to purchase equipment. ### List all in-person products - [GET /in-person/products](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-products/inpersonproductslist.md): List the products that are offered for in-person payments ### Retrieve an in-person product - [GET /in-person/products/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-products/inpersonproductgetbyid.md): Fetches an in-person product via its unique ID ## In-Person SKUs The in-person SKUs API allows you query for the SKUs we offer for in-person payments. SKUs are ultimately the items you order when purchasing equipment. Each SKU is scoped to a specific country and currency. ### List all in-person SKUs - [GET /in-person/skus](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-skus/inpersonskuslist.md): List the SKUs that are offered for in-person payments ### Retrieve an in-person SKU - [GET /in-person/skus/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-skus/inpersonskugetbyid.md): Fetches an in-person SKU via its unique ID ## In-Person Orders The in-person orders API allows you to request physical terminal orders to specific locations. Used in combination with our terminal API you can integrate in-person (card present) payments. ### List in-person orders - [GET /in-person/orders](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-orders/inpersonorderlist.md): Fetches an paginated list of in-person orders ### Retrieve an in-person order - [GET /in-person/orders/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-orders/inpersonordergetbyid.md): Fetches an in-person order via its unique ID ## In-Person Locations The in-person locations API allows you to setup and manage the locations in which terminals reside. ### Create an location at which one or more terminals will reside - [POST /in-person/locations](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-locations/inpersoncreatelocationoperation.md): Use this endpoint to setup a new location which will be used for housing one or more terminals. Note that once created a location's address & geo co-ordinates cannot be changed and instead a new location must be created ### List in-person locations - [GET /in-person/locations](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-locations/inpersonlocationlist.md): Fetches an paginated list of in-person locations ### Retrieve an in-person location - [GET /in-person/locations/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-locations/inpersonlocationgetbyid.md): Fetches an in-person location via its unique ID ### Update an in-person location - [PATCH /in-person/locations/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-locations/inpersonlocationupdatebyid.md): Updates an in-person location via its unique ID. Note that addresses and geo co-ordinates cannot be updated, to do this you must create a new location and delete the old one ### Delete an in-person location - [DELETE /in-person/locations/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-locations/inpersonlocationdeletebyid.md): Deletes an in-person location. Note that once deleted, the location will no longer be available. You can only the location if it has no terminal assigned to it. ## In-Person Terminals The in-person terminals API allows you to setup and manage your physical terminal hardware for in-person (card present) payments. ### Create a terminal to register a physical device - [POST /in-person/terminals](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersoncreateterminaloperation.md): Use this endpoint to setup and register a physical terminal and begin accepting payments. ### List terminals - [GET /in-person/terminals](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminallist.md): Fetches an paginated list of terminals ### Retrieve a terminal - [GET /in-person/terminals/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminalgetbyid.md): Fetches a terminal via its unique ID ### Update a terminal - [PATCH /in-person/terminals/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminalupdatebyid.md): Updates a terminal via its unique ID ### Delete a terminal - [DELETE /in-person/terminals/{id}](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminaldeletebyid.md): Deletes a terminal. Note that once deleted, the terminal will no longer be able to accept payments. ### Initiate a payment on a terminal - [POST /in-person/terminals/{id}/payment](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminalinitpayment.md): Initiate a payment on a specific terminal. The cardholder can present their card to complete the purchase. ### Initiate a refund on a terminal - [POST /in-person/terminals/{id}/refund](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminalinitrefund.md): Initiate a refund on a specific terminal. The cardholder can present their card to complete the refund. ### Cancel the current action on a terminal - [POST /in-person/terminals/{id}/cancel-action](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminalcancelaction.md): Cancel the action that has been initiated and is currently in-progress on a specific terminal. ### Confirm the result of receipt printing via POS for the current action - [POST /in-person/terminals/{id}/confirm-receipt](https://developer.ryftpay.com/documentation/api/reference/openapi/in-person-terminals/inpersonterminalconfirmreceipt.md): Confirm the result of receipt printing via POS for the action that has been initiated and is currently waiting for a receipt to be printed on a specific terminal. This endpoint is required if the transaction's 'receiptPrintingSource' was set to 'PointOfSale'