Skip to main content

RC Request API

The RC Request API is a web service that allows PaysafeCard and PaysafeCash business partners to request new RC (reporting criteria) automatically.

The API is a great choice when the business partner:

  • Regularly needs to onboard more sub-merchants (simply said, frequently requests new RC)
  • Wants to avoid the hassle of files sent by mail
  • Wants to receive real time notifications about the status of your RC requests
  • Wants to know in real time which RC requests need additional information
  • Wants to know in real time when the RC requested are ready for processing

Endpoint​

Production environment: https://api.paysafecard.com/v1/management/

This integration can not be tested on our test environment.

Limits​

  • A maximum of 50 RCs can be requested in a single API call
  • Maximum of 5 products per RC
  • Maximum of 2 features per product

RC status​

During the process of activating the RC, it can have multiple statuses.

ValueDescription
receivedPaysafeCard successfully received the RC request and will initiate the process for its creation.
pendingPaysafeCard needs more information before approving the RC. Please contact psp.support@paysafe.com with the RC name.
declinedThe RC has been declined. Please contact psp.support@paysafe.com or the Key Account Manager with the RC name to clarify the decline reason.
approvedThe RC has been approved and it is ready to be used.

RC Request API Process​

This section describes in detail the technical process of an RC request.

  • The business partner initiates the RC request: POST call request rc
    • PaysafeCard validates the request and answers immediately with http 200 and status "received"
  • PaysafeCard initiates the internal process for a new RC request
  • Once the internal process is completed and the RC is ready to be used, PaysafeCard updates the business partner with the RC status "approved", using the callback_url url provided in the request rc call
    • If PaysafeCard needs more information before completing the request, PaysafeCard updates the business partner with the RC status "pending". In this case the business partner must contact psp.support@paysafe.com with the RC name.
  • (optional) The business partner checks the status of the RC request with a GET request.

Callback notification​

The callback notification is an HTTP POST request sent to the business partner callback_url provided in the request rc call, immediately and everytime the status of an RC is updated by PaysafeCard.

The business partner server must respond with HTTP 200 and the authenticity of the callback notification should be verified.

During the RC Request API integration, the PaysafeCard team will provide a public key to the business partner which can be used to verifiy the authenticity of the callback notification.

In case of technical errors (e.g. socket timeout) or application errors, the callback notification is resubmitted at a regular interval of 1 minute until one of the following criteria is fulfilled:

  • The notification is successfully delivered (i.e. HTTP 200 response from payment server).
  • The maximum number of retry attempts has been reached (currently configured to 5 retries).

How to verifiy the Callback notification​

The callback notification is signed with "rsa-sha256" and the signature can be found in the HTTP "Authorization" header.

HTTP headers​

Content-Type: application/json
Authorization: keyId="1",algorithm="rsa-sha256",signature="OFPVO1uqac0U18LlEedwfdYaIPuuCIsvSxuDRV+nsU33F2TVYapR/JHR0mvJSAZUJWUTJk60PZXPhGF9eQLeIidxX1yJg8JA0pC0/CAt7JbiF39KsjMYMkCPp51q84s1RqAa23D2sljJuvPQYiDJLPlZ7PRSxYaIfmJ6MWzRq4Ku4XVi6OpqgAkO5V205UsDBmp8mxc00w1Eu5yAPoUjelZfxqHl/G2D0e5hWPuggtx/3hx2szFQDJzfHdRBhrlSqcU2WGzByXhy6A6FzeOQVysQNAR1/i+ztlhfCotY11Usb+Uh4yUVwi/I0pbKL+UJZ2VZlI6++SAO7CoQVkBAiw=="
ParameterDescription
keyIdThe signature key version id. It has always the value "1" except if communicated otherwise by the PaysafeCard integration team.
algorithmThe algorithm used for the signature. A callback notification from PaysafeCard will always be signed with "rsa-sha256".
signatureThe signature of the callback notification.

payload​

{
    "submerchants": [
        {
            "id": "rc01",
            "status": "approved",
            "mids": [
                "1000000007",
                "1000000008",
                "1000000009"
            ]
        },
        {
            "id": "rc02",
            "status": "pending",
            "reason_text": "The merchant needs to add a product description."
        },
        {
            "id": "rc03",
            "status": "declined",
            "reason_text":"Website is not fully operational."
        }
    ],
    "request_id": "psc_subid_e8P1asjSI8Gz4S60RwR6"
}

The signature is created as follows:

signature = base64encode(rsa_encrypt(sha256(payload), privateKey))

And it is verified as follows:

rsa_decrypt(base64decode(signature), publicKey) == sha256(payload)

Using the openssl dgst function to verify the signature​

The digest functions can be used to verify digital signatures using message digests. The three steps below ilustrate how this can be done:

  1. Extract the public key from the rsa key file sent with the data package

    openssl rsa -RSAPublicKey_in -in webhook_signer_MANXXXXXXXXXX_1.rsa -out webhook_signer_MANXXXXXXXXXX_1_extracted.pem

  2. Decode the signature of the webhook notification with base64

    Linux: base64 --decode signature.txt > signature_debase64.txt

    Windows: certutil.exe -decode signature.txt signature_debase64.txt

  3. Verify the signature using the openssl dgst function

    The generic name, dgst, may be used with an option specifying the algorithm to be used. The default digest is sha256.

    openssl dgst -sha256 -verify webhook_signer_MANXXXXXXXXXX_1_extracted.pem -signature signature_debase64.txt plaintext_payload.txt
    ParameterDescription
    -verify webhook_signer_MANXXXXXXXXXX_1_extracted.pemVerifies the signature using the public key extracted in step 1. The output is either Verification OK or Verification Failure.
    -signature signature_debase64.txtThe actual signature to verify in plain text, obtained in step 2.
    plaintext_payload.txtThe body of the payload in plain text.

RC Request parameters​

ParameterTypeConstraintExampleDescription
submerchantsarraymandatory-The array containing all the RC details.
idstringmandatoryrc01The RC id being requested. Only alphanumeric characteres allowed (0-9, A-Z and a-z). Size between 1 and 8 characters.
company_namestringmandatoryMy CompanyThe name of the company to wich the RC is being requested for. Max. 70 characteres. Unicode characters are accpected.
country_of_incorporationstringmandatoryATThe RC country of incorporation. ISO 3166-1 (2 letter country code).
licensesarrayoptional*-The licenses array containing all the RC licenses per country. *Mandatory, when the type of business is "BINARY_OPTIONS_SPREAD_BETTING", "FOREX", "PREPAID_CARDS_TOPUPS", "WALLETS", "POKER" or "SPORTSBOOK".
countrystringmandatoryATThe license country. ISO 3166-1 (2 letter country code). Mandatory as soon as a license object is given.
type_of_businessstringmandatorySPORTSBOOKThe RC type of business (sub channel). Max. 60 characters. List of all possible values at the bottom.
mccstringoptional7995The RC MCC (merchant category code) (sub channel). Either type_of_business OR mcc need to be supplied. List of all possible values at the bottom.
webshopsarraymandatory-The webshop array contaning all the RC urls. Max. 5 urls per RC.
urlstringmandatoryhttps://my.test.comThe webshop url. Max. 80 characters. Must be a valid url including protocol (see example).
productsarraymandatory-The RC products and features array. Max. 5 products per RC.
namestringmandatoryPAYSAFECARDThe RC product. Max. 5 products per RC. The possible values are: "PAYSAFECARD", "PAYSAFECASH", "PAGOEFECTIVO", "SAFETYPAY" and "GIFTCARD".
featuresstringoptionalPAYOUTThe RC feature. Max. 2 features per product. The possible values are: "PAYOUT" (only if the product is "PAYSAFECARD) and "REFUND" (only if the product is "PAYSAFECARD" or "PAYSAFECASH").
callback_urlstringmandatoryhttps://notification.comThe callback url to be used by PaysafeCard to inform about the RC status. Max. 1000 characters. Must be a valid url including protocol (see example).

RC Request response parameters​

POST response​

ParameterTypeExampleDescription
submerchantsarray-The RC array containing all the RC response details.
idstringrc01The id of the RC requested.
statusstringreceivedThe status of the RC requested.
midsstring"1000000007", "1000000008"The mids (merchant ids) to which an RC was activated for.
request_idstringpsc_subid_IO7DMI148X183oCcHlS7Request reference.
reason_textstring"Missing information on domain."Reason for a pending/declined RC. In case of "pending", please contact us with the necessary information to proceed with the onboarding.

GET response​

ParameterTypeExampleDescription
idstringrc01The id of the RC requested.
statusstringreceivedThe status of the RC requested.

HTTP status codes​

CodeShort DescriptionDescription
200OKEverything is OK.
201CreatedNew object was successfully created.
400Bad RequestMissing parameter.
401UnauthorizedInvalid or expired API key.
404Not FoundNot found. This is also returned when you try to retrieve a payment that does not exist.
500Internal Server ErrorThis indicates a general technical error on PaysafeCard's end.
501Not ImplementedVersion feature not implemented.
502Bad GatewayInvalid response from upstream system.
503Service UnavailableServer overloaded.
504Gateway TimeoutTimeout from upstream system.

RC Request API Error Codes​

This section describes all the relevant API error codes.

CodeNumber (optional)HTTP StatusDescription
general_technical_error10007500General technical error.
invalid_api_key10008401Authentication failed due to missing or invalid API key. Your key needs to be set to the HTTP auth header.
invalid_request_parameter10028400One of the request parameters failed validation. The message and param fields contain more detailed information.
duplicate_request4001400Submerchant has already been requested.
   400 Bad Request

   {
    "code": "invalid_request_parameter",
    "message": "size must be between 1 and 8",
    "number": 10028,
    "param": "submerchants[0].id"
    }

Annex: Type of business​

The values allowed for the type_of_business (sub channel) parameter are:

ChannelSubchannel (type_of_business)MCC code (mcc)MCC description
ENTERTAINMENTCLOUD_STORAGE_BACKUP_SERVICES7299FILEHOSTING
ENTERTAINMENTROYALTY_FREE_IMAGES7299FILEHOSTING
ENTERTAINMENTSOFTWARE_DOWNLOAD5734SOFTWARE_DOWNLOAD
ENTERTAINMENTMEDIA_AUDIO_VIDEO5815MEDIA_AUDIO_VIDEO
ENTERTAINMENTTCOMMERCE7299FILEHOSTING
ENTERTAINMENTWEBHOSTING4816WEBHOSTING
ENTERTAINMENTDATING7311DATING
ENTERTAINMENTFORTUNE_TELLING_CONSULTING7996FORTUNE_TELLING_CONSULTING
ENTERTAINMENTSOCIAL_NETWORKS_PORTALS4816WEBHOSTING
ENTERTAINMENTMESSAGING_TELEPHONY4814MESSAGING_TELEPHONY
ENTERTAINMENTFILEHOSTING7299FILEHOSTING
ENTERTAINMENTTIPSTER7299FILEHOSTING
ENTERTAINMENTCLASSIFIEDS7311DATING
ENTERTAINMENTCHARITY8398CHARITY
GAMESONLINE_GAMES5818ONLINE_GAMES
GAMESSKILL_GAMES7994SKILL_GAMES
GAMESFANTASY_SPORTS7994SKILL_GAMES
GAMESVIRTUAL_ITEMS5818ONLINE_GAMES
GAMESESPORTS7995SPORTSBOOK
GAMESGAME_SERVER4816WEBHOSTING
GAMESGAMES_ERETAIL5818ONLINE_GAMES
GAMESSTREAMING_GAMES7299FILEHOSTING
GAMESBOXED_VIDEO_GAMES_PHYS_COPIES5945BOARD_GAMES_TABLETOPS
GAMESGAMES_MERCHANDISE5945BOARD_GAMES_TABLETOPS
GAMESBOARD_GAMES_TABLETOPS5945BOARD_GAMES_TABLETOPS
GAMESGAMES_TICKETS7922GAMES_TICKETS
GAMESGAMES_HARDWARE5399CONSUMER_GOODS
GAMESCOMIC_BOOKS_GAMES_LITERATURE5945BOARD_GAMES_TABLETOPS
GAMESTOYS5945BOARD_GAMES_TABLETOPS
GAMESSOCIAL_GAMBLING7994SKILL_GAMES
ERETAILCONSUMER_GOODS5399CONSUMER_GOODS
ERETAILAUCTIONS8999AUCTIONS
ERETAILVOUCHERSHOP6012WALLETS
ERETAILFASHION5691FASHION
ERETAILELECTRONICS5732ELECTRONICS
ERETAILSPORTS_FITNESS5941SPORTS_FITNESS
ERETAILHOME5712HOME
ERETAILDIY_HOBBY5945BOARD_GAMES_TABLETOPS
ERETAILPERSONAL_CARE5977PERSONAL_CARE
ERETAILDRUGS_MEDICATION5912DRUGS_MEDICATION
ERETAILLUXURY_GOODS5399CONSUMER_GOODS
ERETAILDELIVERY_SERVICE4214DELIVERY_SERVICE
ERETAILTICKETING_FOR_EVENTS7922GAMES_TICKETS
ERETAILOTHER_ERETAIL5999OTHER_INDUSTRIES
GIFTCARDSGIFTCARDS6012WALLETS
VOUCHERSVOUCHERS6012WALLETS
FINANCIAL_SERVICESBINARY_OPTIONS_SPREAD_BETTING6211FOREX
FINANCIAL_SERVICESWALLETS6012WALLETS
FINANCIAL_SERVICESPREPAID_CARDS_TOPUPS6012WALLETS
FINANCIAL_SERVICESFOREX6211FOREX
FINANCIAL_SERVICESCOLLECTION_SERVICE6012WALLETS
FINANCIAL_SERVICESALTERNATIVE_BANKING6012WALLETS
FINANCIAL_SERVICESBANK_PAYSAFE_LICENSE6012WALLETS
FINANCIAL_SERVICESBANK_BANK_LICENSE6012WALLETS
FINANCIAL_SERVICESINSURANCE5960INSURANCE
FINANCIAL_SERVICESLOAN_PROVIDER6012WALLETS
FINANCIAL_SERVICESMONEY_REMITTANCE6012WALLETS
POKERPOKER7995SPORTSBOOK
POKERLOTTERY7995SPORTSBOOK
POKERCASINO7995SPORTSBOOK
POKERBINGO7995SPORTSBOOK
SPORTSBOOKSPORTSBOOK7995SPORTSBOOK
SPORTSBOOKESPORTS_BETTING7995SPORTSBOOK
PAYMENT_SERVICE_PROVIDERMERCHANT_OF_RECORD6012WALLETS
PAYMENT_SERVICE_PROVIDERPAYMENT_GATEWAY6012WALLETS
PAYMENT_SERVICE_PROVIDERTECHNICAL_SERVICE_PROVIDER6012WALLETS
PAYMENT_SERVICE_PROVIDERAGGREGATOR6012WALLETS
PAYMENT_SERVICE_PROVIDERSHOP_MODULE_ECOMMERCE_PLATFORM6012WALLETS
PAYMENT_SERVICE_PROVIDERPLATFORM_PROVIDER6012WALLETS
PAYMENT_SERVICE_PROVIDEROTHER_PSP6012WALLETS
ADULTADULT_MEDIA5967ADULT_MEDIA
ADULTADULT_ERETAIL5967ADULT_MEDIA
ADULTADULT_CLASSIFIEDS5967ADULT_MEDIA
ADULTADULT_DATING7273ADULT_DATING
ADULTADULT_GAMES5967ADULT_MEDIA
TRAVELTRAVEL_PORTAL4722OTHER_TRAVEL
TRAVELHOSPITALITY4722OTHER_TRAVEL
TRAVELMOBILITY_SERVICES4722OTHER_TRAVEL
TRAVELOTHER_TRAVEL4722OTHER_TRAVEL
UTILITIESUTILITY_BILL_PAYMENT6012WALLETS
UTILITIESUTILITY_PREPAID6012WALLETS
CRYPTOCRYPTO_RESELLER6051CRYPTO_EXCHANGE
CRYPTOCRYPTO_EXCHANGE6051CRYPTO_EXCHANGE
OTHER_INDUSTRIESOTHER_INDUSTRIES5999OTHER_INDUSTRIES
OTHER_INDUSTRIESREFERRAL_PARTNER7311DATING
OTHER_INDUSTRIESEDUCATION8299EDUCATION
OTHER_INDUSTRIESGOVERNMENT9399GOVERNMENT
OTHER_INDUSTRIESREAL_ESTATE_HOUSING6513REAL_ESTATE_HOUSING
OTHER_INDUSTRIESHEALTHCARE8099HEALTHCARE