Skip to main content

Documentation

Support Tickets API Guide

Disclaimer

Beta-stage product. This solution is in the beta stage and therefore considered a Beta-stage product. It is clarified that if there are any faults and/or issues, it will not affect your obligation to provide us with the requested and accurate information and documentation. This information should be delivered with no dependency on the stability and performance of the product. If the product is not working as expected, you should use any other alternative to fulfill your obligations as described above.

Overview

The Support Tickets API lets partners and merchants raise and track support tickets from their own systems, without logging in to the Client Portal or Partner Portal. Tickets created through the API are the same tickets that the portals create. Replies from Rapyd support appear in the ticket details, so you can follow a conversation without leaving your own tooling.

With the API you can:

  • Get the allowed values for a ticket (category, environment, subject, and similar fields).

  • Create a ticket, with optional file attachments.

  • List your open or closed tickets and read one ticket with its comments.

  • Edit the subject or description of an open ticket, and close a ticket.

  • Add comments, with optional files, to an open ticket.

  • Get a download link for a file attached to a ticket.

Rapyd enables the API for each organization. If Rapyd has not enabled it for your organization, requests return 404 with an empty body.

Access rules

  • A caller can read and write only the tickets of its own organization.

  • A partner can also act for the sub-merchants linked to it, by sending the merchant's organization token as merchant_account_id when it creates a ticket. A partner cannot act for a merchant outside its own sub-merchants.

  • A ticket that does not belong to the caller returns 404 ERROR_SUPPORT_TICKET_NOT_FOUND. The response does not reveal whether the ticket exists.

  • You cannot edit a closed ticket, comment on it, or add files to it. The request returns 400 ERROR_SUPPORT_TICKET_CLOSED.

Authentication

Sign every request with the standard Rapyd request signature of the calling organization. Send the access_key, salt, timestamp, and signature headers on every call. Set Content-Type: application/json on requests that have a JSON body. The file upload is the exception: it uses multipart/form-data, and you sign it without a body.

Conventions

  • Every response uses the standard Rapyd envelope: a status object and a data object. Successful calls return status.status of SUCCESS.

  • Timestamps are Unix time in seconds.

  • A ticket status is open or closed.

  • Comments are plain text. The direction of a comment is from your point of view: outgoing is anything you added (through the portal, the API, or email), and incoming is a reply from Rapyd support.

  • merchant_account_id is the organization token of a merchant, not its organization ID.

Flows

Create a ticket

  1. Call Get Ticket Options to read the allowed values and limits. The values are configuration, so they can change without notice.

  2. Call Create Ticket with the required fields. The response returns the new ticket ID and a status of open.

Create a ticket or comment with attachments

Files are never sent in the ticket calls. The ticket calls stay JSON only, and files go through a separate upload step.

  1. Call Upload Attachment once for each file. Each call accepts one file and returns a batch token in data.id.

  2. Pass up to 5 tokens in the attachments array of Create Ticket or Add Comment .

  3. If the API cannot attach a file, it still creates the ticket or comment, and it returns the tokens that failed in failed_attachments.

A token belongs to the organization that uploaded the file. A partner uploads with its own keys, also when it acts for a merchant, and uses the token in its own call.

Allowed file types are .jpg, .jpeg, .png, .pdf, and .csv. Each file can be up to 10 MiB, and each ticket or comment call accepts up to 5 files. The first bytes of a file must match its extension, and a CSV must be plain text.

Raise a ticket for a sub-merchant (partners)

  1. Follow the steps in Create a ticket.

  2. Add merchant_account_id with the organization token of the merchant to the create request. Without it, the ticket belongs to the partner.

  3. The merchant must be an active merchant of the calling partner. Otherwise the request returns 403 ERROR_SUPPORT_TICKET_MERCHANT_NOT_LINKED.

  4. Use merchant_account_id as a filter in List Tickets to see the tickets that you raised for a merchant. A partner sees its own tickets and the tickets it raised for its merchants.

Track and update a ticket

  1. Call List Tickets to see open or closed tickets. Results come in pages, and you can filter them by ticket ID, subject, and merchant.

  2. Call Get Ticket to read one ticket with its comments, including replies from Rapyd support, and the names of its attachments.

  3. Call Add Comment to reply to support.

  4. Call Edit Ticket to change the subject or description of an open ticket.

  5. Call Close Ticket when you resolve the issue. Closing a ticket that is already closed returns the ticket unchanged. You cannot reopen a closed ticket through the API.

Download an attachment

  1. Call Get Ticket and find the attachment id in attachments. The ticket details list the name and extension of each attachment, but no link.

  2. Call Download Attachment with the ticket ID and the attachment ID. The response contains a short-lived signed url.

  3. Download the file directly from the url. Do not send Rapyd authentication headers. Request a new link when you need the file again, because the link expires.

Allowed values

This section lists the current values. Always use Get Ticket Options for the up-to-date list.

Field

Allowed values

category

GeneralIssueOrSandboxQuery, TechnicalIssue, Financial Issue

environment

Production, Sandbox

issue_first_identified

Past24Hours, PastWeek, MoreThanAWeek, NotRelevant

transactions_users_affected

SingleTransactionUser, PartialTransactionsUsersAreAffected, AllTransactionsUsersAreAffected, NotRelevant

total_transaction_value

LessThan1kUSD, 1kTill100kUSD, GreaterThan100kUSD, NotRelevant

The subject depends on the category and the environment. When a category offers other, send Other - <free text> with up to 120 characters of free text.

Category

Environment

Subject keys

GeneralIssueOrSandboxQuery

Production

kyb, compliance, bank_account, client_portal_navigation, account_modification, other

GeneralIssueOrSandboxQuery

Sandbox

client_portal_navigation, account_modification, other

TechnicalIssue

Production, Sandbox

plugins, api, transactions, client_portal, issuing_card_or_virtual_account, other

Financial Issue

Production

transaction_status, fx_conversion, wallet, chargebacks, fees, reports, settlement, recall, other

Financial Issue

Sandbox

fx_conversion, wallet, chargebacks, other

The API accepts the token field (a related object token) only for the TechnicalIssue and Financial Issue categories.

Limits

Item

Limit

Description

1500 characters

Comment text

1500 characters

Related object token

1500 characters

Text after Other - in a subject

120 characters

Contact email

254 characters

Attachments per ticket or comment call

5

File size

10 MiB

Page size in List Tickets

1 to 100

Results reachable in List Tickets

page multiplied by limit cannot exceed 10,000

Errors

For the errors that the API can return, see Support Ticket Errors .

Requests

Ticket options

Read the allowed values and limits for creating a ticket.

Attachments

Upload files to attach to tickets and comments, and download files attached to a ticket.

Tickets

Create, list, read, edit, and close support tickets.

Comments

Add comments to an open ticket.

In this section: