API

Response Formats

Although the response parameters of the Craftgate API differ depending on whether the transaction is successful and whether a single or multiple result is returned, they use a common framework among themselves.

Failed Transactions

It is the return format used when a systematic or fictional error occurs. It only contains a field named errors that contains error information.

Parameter Name Type Always Exist Description
errors Error Yes Contains information about the error that occurred. For detailed information, see: Payment Error Groups

Successful Transactions

Responses given as a result of successful transactions contain different parameters depending on whether the transaction result is singular or plural.

Single Result Transactions

It is the return format used for transactions or queries that produce single results, such as receiving payment, returning payment, creating a buyer, viewing merchant details. It only contains a field named data that contains the result of the transaction.

Parameter Name Type Always Exist Description
data any No The result of the operation or query performed. Structure and contents are detailed on the documentation page for the relevant transaction or query.

Sample: Example of a forwarded response for the detail of a payment:

{
    "data": {
        "id": 5,
        "createdDate": "2021-11-15T14:07:18",
        "price": 100.00000000,
        "paidPrice": 100.00000000,
        ...
    }
}

Multiple Result Transactions

It is the answer format that is returned as a result of transactions or queries that have the potential to produce multiple results, such as search or listing.

Parameter Name Type Always Exist Description
items any[] Yes It contains the results retrieve as a result of the operation or query. The structure and contents of the results are detailed on the documentation page for the relevant transaction or query.
totalSize number No Returned as a result of operations with pagination such as search or listing. It refers to the total number of results reached as the result of the query. This field is not included in the return of failed transactions.
size number No It is returned as a result of operations with pagination such as search or listing. Indicates the number of results to exist per page in the query. This field is not included in the return of failed transactions.
page number No It is returned as a result of operations with pagination such as search or listing. Indicates the number of page in query. This field is not included in the return of failed transactions.

Sample: Example of response when the list of payments is requested:

{
    "data": {
        "items": [
            {
                "id": 5,
                "createdDate": "2021-11-15T14:07:18",
                ...
            },
            {
                "id": 4,
                "createdDate": "2021-11-15T14:07:18",
                ...
            },
            {
                "id": 3,
                "createdDate": "2021-11-15T14:07:18",
                ...
            }
        ],
        "page": 0,
        "size": 25,
        "totalSize": 3
    }
}

No result transactions

A blank response may be given as a result of ineffective transactions such as deleting a stored card. Although such transactions are quite rare, it is recommended to act with the expectation that no response will be given in deletion transactions. On the other hand, since these answers can be returned with 204 No Content HTTP code and this code indicates successful transactions, it is not recommended to only check if the status code is 200 OK when checking whether the request is successful.

Constants and Enum Values

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

General

Status

Status that can be used when communicating with the Craftgate API:

Value Description
ACTIVE Active, represents records that available to be used
PASSIVE Passive, represents records that not available to be used

Currencies

Currencies that can be used when communicating with the Craftgate API:

Value Description
TRY Turkish Lira
USD U.S. Dollar
EUR Euro
GBP British Pound
CNY Chinese Yuan
ARS Argentine Peso
BRL Brazilian Real

Card Types

Types expressing the configuration of the use of card:

Value Description
CREDIT_CARD Credit card
DEBIT_CARD Debit card
PREPAID_CARD Prepaid card

Card Associations

They are the names that express the card provider associations.

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

Member

Member Types

Value Description
PERSONAL Personal member
PRIVATE_COMPANY Private Company member
LIMITED_OR_JOINT_STOCK_COMPANY Limited or joint stock company member

Payout Destinations

Value Description
IBAN IBAN
WALLET Member wallet

Payout Merchant Types

Value Description
MERCHANT Merchant
SUB_MERCHANT_MEMBER Sub merchant member

Payout Transaction Types

Value Description
PAYMENT Payout for payments
WITHDRAW Payout for withdraws
RAS Payout for refund after settlement

Payout Return Status

Value Description
NOT_BOUNCED The first value that occurs when money is sent. It means that the money transfer is sent on the first try.
BOUNCED The status that occurs when the money transfer is marked as returned.
UPDATED The status that occurs when the sub-merchant information is updated together with the Name / Surname / Iban information that is the subject of money transfer.
PAYOUT_STARTED The status that occurs when sending money again for a returned transaction.
PAYOUT_COMPLETED The status that occurs after the money transfer is made again for a returned transaction.

Payments

Payment Types

Values expressing the way a payment is collected:

Value Description
CARD_PAYMENT Payment fully deducted from card
DEPOSIT_PAYMENT Top-up payment from card
WALLET_PAYMENT Payment fully deducted from wallet
CARD_AND_WALLET_PAYMENT Payment, some of which is debited from a card and some from a wallet
BANK_TRANSFER Bank transfer

Payment Groups

Group names expressing the product or service to which the payment is done:

Value Description
PRODUCT Product
LISTING_OR_SUBSCRIPTION Ad, listing, service or subscription

Payment Status

Values expressing the status of the payment:

Value Description
FAILURE Payment is failed
SUCCESS Payment is successful
INIT_THREEDS 3D Secure payment is initiated.
CALLBACK_THREEDS After entering the sms code on the bank's 3D Secure SMS page, the transaction is waiting by Craftgate. In this case, Craftgate is waiting for buyer return to the callback address of merchant and complete the payment.

Payment Item Confirmation Status

Values expressing approval status for a payment item

Value Description
WAITING_FOR_APPROVAL Awaiting approval
APPROVED Approved

Payment Phases

Transaction type/phase of the payment at the bank:

Value Description
AUTH In standard provision transaction, the payment is set as this status value.
PRE_AUTH If a Pre-authorization is made, the payment phase takes this value. In the pre-authorization process, the payment is not withdrawn directly, the relevant amount is blocked on the user's card by the bank during the provisioning period.
POST_AUTH In case of capture for a pre-authorized transaction, the payment phase takes this value.

Payment Methods

Users can pay below methods from Common Payment Page/Form;

Değer Açıklama
CARD User pays with card
MASTERPASS User pays with own Masterpass account
PAPARA User pays with own Papara account
PAYONEER User pays with own Payoneer account
SODEXO User pays with own Sodexo account
EDENRED User pays with own Edenred account

Payout Status

Values expressing the Payout status:

Value Description
CANCELLED Money transfer canceled
NO_PAYOUT Money transfer will not be done
WAITING_FOR_PAYOUT Waiting for money transfer
PAYOUT_STARTED Money transfer started
PAYOUT_COMPLETED Money transfer completed
CANCELLED Money transfer cancelled

Payout Types

Values expressing Payout Types:

Value Description
SETTLEMENT Represents money transfers due to Payment/Cancellation/Return transactions
BOUNCED_SETTLEMENT Represents a money transfer to resend transactions that have been refunded for some reason after the money has been sent
WITHDRAW Represents money transfers based on sub-merchants' wallet balance withdrawal requests

Payout Source

Values expressing the Payout Source:

Value Description
COLLECTION Represents money transfers due to Payment/Cancellation/Return transactions
BOUNCED Represents a money transfer to resend transactions that have been refunded for some reason after the money has been sent
WITHDRAW Represents money transfers based on your sub-merchants' wallet balance withdrawal requests

MD Status

These are the numerical values transmitted to Craftgate by the bank after verification for payments made with 3D Secure. Although banks and payment institutions sometimes return with their unique MD Status figures, the values in the table below can be accepted as standard.

MD Status Description
0 3D Secure verification or signature invalid
1 Full Verification, processing can be continued
2 Card holder or bank not registered in the system
3 The bank of the card is not registered in the system
4 Verification attempt, cardholder has chosen to register later in the system
5 Unable to verify
6 3D Secure error
7 System error

Payment Sources

Indicates which type of integration a payment is coming from.

Value Description
API via API
MASTERPASS via Masterpass
CHECKOUT_FORM via Common Payment Form

Alternative Payment Methods

Alternative Payment Methods which are supported by Craftgate

Değer Açıklama
PAPARA Papara
PAYONEER Payoneer
SODEXO Sodexo

Additional Actions Of Alternative Payment Methods

Additional Action of Alternative Payment Methods which are supported by Craftgate

Değer Açıklama
REDIRECT_TO_URL Redirect the user to the url
OTP_REQUIRED OTP verification code is required
NONE There is no additional action

Reward Types

Indicates the type of rewards provided by the bank.

Value Description
REWARD_MONEY Reward/Point Usage
ADDITIONAL_INSTALLMENT Additional Installment
POSTPONING_INSTALLMENT Postpone Installment
EXTRA_POINTS Extra point
GAINING_MINUTES Gaining minutes
POSTPONING_STATEMENT Statement Postponement

Refunds

Refund Status Types

Values that express the status of a refund.

Value Description
SUCCESS Successful refund
FAILURE Failed refund

Refund Status Types of Payment

Values that represent the refund status of a payment.

Value Description
NO_REFUND Payment not successful
NOT_REFUNDED Payment has no refund
PARTIAL_REFUNDED Partially refunded
FULLY_REFUNDED Fully refunded

Refund Types

Values that indicate where a refund amount will be refunded.

Value Description
CARD To Card
WALLET To Wallet

Money Transfer

Money Transfer Request Result Status

It is the value that expresses the result of receiving a money transfer request.

Value Description
SUCCESS Money transfer completed successfully.
FAILURE Money transfer failed.
NO_RECORD_FOUND No record found to send money

Transferring/Withdrawing Money from/to Wallet

Types of Wallet Transfer/Withdrawal

The reasons for sending money to the member defined by the merchant in the Craftgate system.
The default figure for a standard merchant is REDEEM_ONLY_LOYALTY. If sent optionally, REDEEM_ONLY_LOYALTY figure should be sent.

Value Description
REDEEM_ONLY_LOYALTY The type that can be used within the scope of loyalty programs. This type of money sent to the member can only be spent within the system by the member.

Daily Transaction Report

Daily Transaction Report File Types

Value Description
CSV Comma Separated Values file extension.
XLSX Excel file extension.

Signature Calculation

Any direct request to the Craftgate APIs must be authenticated using the merchant account's access keys. You can see the access keys of the merchant via Merchant Panel.

If you are using Craftgate Client, it will be sufficient to give the access keys information to the Craftgate object as a parameter. If you are not using a client, the following steps are obligatory to perform.

To do the authentication of your merchant account, you must send the following headers in every request you make to API Gateway:

Header Name Description
x-api-key API access key
x-rnd-key Custom generated random string value
x-auth-version The version number of the authentication algorithm. If you are not sure what value you should give, you can give V1
x-signature Signature created using the above parameters, secret access password and some information specific to the request.
For more information, see: Signature Calculation Algorithm

Signature Calculation Algorithm

A signature is a validation value used to verify that the request comes from the right source. Since it is specific to the request, it must be recalculated and sent with every request. To calculate the signature figure:

  • The following figures are merged
    • Raw URL of the request (including hostname, protocol and query string)
    • API access key (API Key) of the merchant account
    • The secret key of the merchant account
    • A string randomly generated upon request
    • The body of the request, if available
  • Calculate the SHA-256 hash of the concatenated string
  • Calculate Base64-encrypted hash

Sample 1

Parameters
Name Value
Request URL https://api.craftgate.io/onboarding/v1/members/1
Request Body -
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T
Signature Calculation
  • Full URL:
    https://api.craftgate.io/onboarding/v1/members/1
  • Query String: -
  • API Key:
    key-1
  • Secret Key:
    FooBar123!
  • Random Key:
    Xa15Fp11T
  • Request Body: -
  • Concatenated String:
    https://api.craftgate.io/onboarding/v1/members/1key-1FooBar123!Xa15Fp11T
  • Signature:
    y1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA=
Headers to be Added on Request:
Name Value
x-api-key key-1
x-rnd-key rGciw1df
x-auth-version V1
x-signature y1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA=

Sample 2

Parameters
Name Value
Request URL https://api.craftgate.io/onboarding/v1/members
Request Body {"email": "haluk.demir@example.com","name": "Haluk Demir","phoneNumber": "905551111111","address": "Beylerbeyi Cad. Lale Sok. No: 38 Daire: 3 Üsküdar","identityNumber": "11111111110","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T
Signature Calculation
  • Full URL:
    https://api.craftgate.io/onboarding/v1/members
  • Query String: -
  • API Key: key-1
  • Secret Key:
    FooBar123!
  • Random Key:
    Xa15Fp11T
  • Request Body:
    {"email": "haluk.demir@example.com","name": "Haluk Demir","phoneNumber": "905551111111","address": "Beylerbeyi Cad. Lale Sok. No: 38 Daire: 3 Üsküdar","identityNumber": "11111111110","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Concatenated String:
    https://api.craftgate.io/onboarding/v1/memberskey-1FooBar123!Xa15Fp11T{"email": "haluk.demir@example.com","name": "Haluk Demir","phoneNumber": "905551111111","address": "Beylerbeyi Cad. Lale Sok. No: 38 Daire: 3 Üsküdar","identityNumber": "11111111110","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Signature:
    nv8y2bSnFjYNRzVRqzkHTK5RXKuN04hoK6fLE2+nzTw=
Headers to be Added on Request:
Name Value
x-api-key key-1
x-rnd-key Xa15Fp11T
x-auth-version V1
x-signature pYuONv7/IgM14OAuSoANWUUgfVSwRX3bYeSZLXltb04=