General API Information

Response Parameters

Although response parameters of OderoPay API vary depending on sent requests, they are using a common structure.

Error Responses

Returned when a system or a request error occurs. Response only returns parameter called errors, which contains error information.

Parameter Type Availability Description
errors Error Always Contains information about the error that has occurred. For detailed information on different various error codes: Payment Error Codes

Success Responses

Responses returned as a result of successful requests contain different parameters depending on whether the response is singular or plural.

Single Result

Response format used for requests that produce single results, such as receiving a payment, returning a payment, creating a buyer, viewing merchant details. Response only returns a parameter called data, which contains the result of the operation.

Parameter Type Availability Description
data any Optional Result nature and content are detailed on the documentation page for the relevant request type.
Multiple Result

Response format returned as a result of operations or queries that have the potential to produce multiple results, such as searching or listing.

Parameter Type Availability Description
items any[] Always The nature and content of the results are detailed on the documentation page for the relevant request types.
totalSize long Optional It is returned as a result of pagination operations such as searching or listing. It refers to the total number of results obtained as a result of the query. This field is not included in the returns of erroneous transactions.
size long Optional It is returned as a result of pagination operations such as searching or listing. It refers to the number of results desired to be returned per page in the query. This field is not included in the returns of erroneous transactions.

Empty Response

Operations such as deleting a hidden card may result in an empty response. The rather rare combination of such operations is recommended to move the deletion to the interval in which it will not turn into a response. On the other hand, these responses can be returned with the HTTP code 204 No Content, which indicates successful transactions. It is not recommended to just look at 200 OK when checking whether the request is successful or not.

Enums

Some constants and enum values that used as request and response parameters of different operations are listed under this heading.

Currency

Value Description
TRY Turkish Lira
AZN Azerbaijani Manat

NOTE: You need to use currencies depending on the country of operations. For example, if you are an Azerbaijani merchant you need to send requests as AZN, or if you are Türkiye-based then you will use TRY.

Card Types

Value Description
CREDIT_CARD Credit Card
DEBIT_CARD Debit card
PREPAID_CARD Prepaid card

Card Associations

Value Description
VISA Visa
MASTER_CARD Master Card
AMEX American Express
TROY Troy

Sub-Merchant Types

Value Description
PRIVATE_COMPANY Private Company/Sole Proprietorship Company
LIMITED_OR_JOINT_STOCK_COMPANY LLC or OJS/CJS

Payment Types

Value Description
CARD_PAYMENT Payment charged entirely from card
DEPOSIT_PAYMENT Top-up payment
WALLET_PAYMENT Payment charged entirely from wallet
CARD_AND_WALLET_PAYMENT Payment partially charged from card and partially from wallet
BANK_TRANSFER Money order/EFT payment

Payment Groups

Value Description
PRODUCT Product
LISTING_OR_SUBSCRIPTION Service, listing or subscription
SUBSCRIPTION Subscriptions/Recurring Payments

Payment Statuses

Value Description
FAILURE Payment failed
SUCCESS Payment successful
INIT_THREEDS 3D Secure started
CALLBACK_THREEDS 3D Secure in callback state

MD Status

These are numerical values transmitted to OderoPay API by the bank after payments verification is made using 3D Secure. Although banks and payment institutions sometimes return their own MD Status values, the values in the table below can be considered standard.

Value Description
0 3D Secure signature or verification code is invalid
1 Verification successful
2 Card owner or bank is not registered in the system
3 Card bank is not registered in the system
4 Verification error, cardholder chose to register to the system later
5 Validation error
6 3D Secure error
7 System error

Refund Types

Value Description
CARD To card
WALLET To wallet

Settlement Statuses

Value Description
WAITING_FOR_APPROVAL Waiting for confirmation for money transfer
APPROVED Money transfer confirmed
PAYOUT_STARTED Money transfer has started

Signature Algorithm

Every request to be made directly to OderoPay APIs requires authentication using the access keys of the merchant account. You can access api and secret key information of the merchant from Merchant Panel.

If you are using OderoPay products, it will be sufficient to provide the access keys information as a parameters. If you are not using a client, it is mandatory to perform the following operations.

To authenticate with your merchant account, you must send the following headers in every request you make to API!

Header Description
x-api-key API key A.K.A. public key
x-rnd-key A custom-generated random string value
x-auth-version Version number of the authentication algorithm. If you are not sure what value you should give, you can give V1
x-signature The signature value that was calculated using the above parameters, the secret key and information specific to the request made. For more information. Signature Calculation Algorithm

Signature Calculation Algorithm

Signature is a checksum value used to verify that the request came from the correct source. Since it is specific to the request made, it must be recalculated for each request and sent along with the request.

Signature is specific to each request!

  1. Join the following values end to end
    • Raw version of the URL from which the request was made (including hostname, protocol and query string)
    • API key of the merchant account
    • Secret key of the merchant account
    • A custom-generated random string
    • The body of the request, if available
  2. Calculate SHA-256 hash of the concatenated string
  3. Calculate Base64 encrypted hash

Examples



Parameters

Name Value
URL https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1
Request Body
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T

Signature Algorithm

  • Full URL: https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1
  • Query String:
  • API Key: key-1
  • Secret Key: FooBar123!
  • Random Key: Xa15Fp11T
  • Request Body:
  • Concatenated String: https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1key-1FooBar123!Xa15Fp11T
  • Signature: L/F2ZAOH/AGXZPIULNHDGOFZ+D5JS1097UP6RH11VSO=

Resulted Header

Name Value
x-api-key key-1
x-rnd-key rGciw1df
x-auth-version V1
x-signature L/F2ZAOH/AGXZPIULNHDGOFZ+D5JS1097UP6RH11VSO=





Parameters

Name Value
URL https://api-gateway.oderopay.com.tr/onboarding/v1/buyers
Request Body {"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T

Signature Algorithm

  • Full URL: https://api-gateway.oderopay.com.tr/onboarding/v1/buyers
  • Query String:
  • API Key: key-1
  • Secret Key: FooBar123!
  • Random Key: Xa15Fp11T
  • Request Body: {"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Concatenated String: https://api-gateway.oderopay.com.tr/onboarding/v1/buyerskey-1FooBar123!Xa15Fp11T{"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Signature: IRWQTISFBKCSM/NGZZ9XGN9PCTBXC0YSUJIBZMUZ9VS=

Resulted Header

Name Value
x-api-key key-1
x-rnd-key Xa15Fp11T
x-auth-version V1
x-signature IRWQTISFBKCSM/NGZZ9XGN9PCTBXC0YSUJIBZMUZ9VS=