API

Response Formats
Constants and Enum Values
Signature Calculation

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.

errors

Error

Contains information about the error that occurred. For detailed information, see: Payment Error Groups

errorCode

string

The unique code for the error

errorDescription

string

Explanatory message that mentions the attribute of the error

errorGroup

string

(see: Payment Error Groups) Error group sent in case of an error is occurred that is payment related

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.

data

any

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.

items

any[]

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

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

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

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
`AED`	United Arab Emirates Dirham
`IQD`	Iraqi Dinar
`AZN`	Azerbaijani Manat
`KZT`	Kazakhstani Tenge

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

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
`PLUXEE`	User pays with own Pluxee card
`EDENRED`	User pays with own Edenred card
`EDENRED_GIFT`	User pays with own Edenred gift card
`PAYPAL`	User pays with own PayPal account
`AFTERPAY`	User pays with own Afterpay account
`KLARNA`	User pays with own Klarna account
`STRIPE`	User pays with own Stripe account

Payout Status

Values expressing the Payout status:

Value	Description
`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

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
`PLUXEE`	Pluxee
`EDENRED`	Edenred
`EDENRED_GIFT`	Edenred Gift Card
`PAYPAL`	PayPal
`KLARNA`	Klarna
`AFTERPAY`	Afterpay
`STRIPE`	Stripe

Offline Alternative Payment Methods

Offline Alternative Payment Methods which are supported by Craftgate

Değer	Açıklama
`FUND_TRANSFER`	Pay with Fund Transfer
`CASH_ON_DELIVERY`	Cash on Delivery

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
`SHOW_HTML_CONTENT`	Render returning HTML at the screen
`WAIT_FOR_WEBHOOK`	Wait for Webhook message from Craftgate
`APPROVAL_REQUIRED`	Approve is required to complete flow
`NONE`	There is no additional action

Category Codes

Değer	Açıklama
`MOBILE_PHONE_PRICE_ABOVE_REGULATION_LIMIT`	Mobile phone whose price is above regulation limit
`MOBILE_PHONE_PRICE_BELOW_REGULATION_LIMIT`	Mobile phone whose price is below regulation limit
`TABLET`	Tablet
`COMPUTER`	Computer
`CONSTRUCTION_MARKET`	Construction Market
`GOLD`	Gold
`DIGITAL_PRODUCTS`	Digital Products
`SUPERMARKET`	Supermarket
`WHITE_GOODS`	White Goods
`WEARABLE_TECHNOLOGY`	Wearable Technology
`SMALL_HOME_APPLIANCES`	Small Home Appliances
`TV`	Tv
`GAMES_CONSOLES`	Games Consoles
`AIR_CONDITIONER_AND_HEATER`	Air Conditioner & Heater
`ELECTRONICS`	Electronics
`ACCESSORIES`	Accessories
`MOM_AND_BABY_AND_KIDS`	Mom & Baby & Kids
`SHOES`	Shoes
`CLOTHING`	Clothing
`COSMETICS_AND_PERSONAL_CARE`	Cosmetics & PersonalCare
`FURNITURE`	Furniture
`HOME_LIVING`	Home Living
`AUTOMOBILE_MOTORCYCLE`	Automobile Motorcycle
`OTHER`	Other

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
`PROVIDER`	To Provider (Card or APM)
`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_LOYALTYfigure 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 (Please note that the SHA-256 output should be digest (bytes) and the byte encoding should be UTF-8.)
Calculate Base64-encrypted hash

If you want to calculate the signature for the requests you send to the Craftgate Sandbox, the information used should include the information used for the sandbox account. In other words, https://sandbox-api.craftgate.io, which is the sandbox api url in the url, api key and secret key information of your sandbox account. In the live environment, this information should belong to your live account. That is, https://api.craftgate.io, which is the api url of the live system in the url, and the api key and secret key of your live account.

Make sure that the encoding of the payload content does not change during the calculation. If it changes, you will get the error "Signature is not equal!" because it will be different in the payload and different in the computed data.

For the details of the algorithm, you can check the codes below for our clients.

Java .NET PHP Node.js Go

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","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","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","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=

Response Formats ​

Failed Transactions ​

Successful Transactions ​

Single Result Transactions ​

Multiple Result Transactions ​

No result transactions ​

Constants and Enum Values ​

General​

Status ​

Currencies ​

Card Types ​

Member​

Member Types ​

Payout Destinations ​

Payout Merchant Types ​

Payout Transaction Types ​

Payout Return Status ​

Payments​

Payment Types ​

Payment Groups ​

Payment Status ​

Payment Item Confirmation Status ​

Payment Phases ​

Payment Methods ​

Payout Status ​

Payout Types ​

Payout Source ​

MD Status ​

Payment Sources ​

Alternative Payment Methods ​

Offline Alternative Payment Methods ​

Additional Actions Of Alternative Payment Methods ​

Category Codes ​

Reward Types ​

Refunds​

Refund Status Types ​

Refund Status Types of Payment ​

Refund Types ​

Money Transfer​

Money Transfer Request Result Status ​

Transferring/Withdrawing Money from/to Wallet​

Types of Wallet Transfer/Withdrawal ​

Daily Transaction Report​

Daily Transaction Report File Types ​

Signature Calculation ​

Signature Calculation Algorithm​

Sample 1​

Parameters​

Signature Calculation​

Headers to be Added on Request:​

Sample 2​

Parameters​

Signature Calculation​

Headers to be Added on Request:​

Response Formats

Failed Transactions

Successful Transactions

Single Result Transactions

Multiple Result Transactions

No result transactions

Constants and Enum Values

General

Status

Currencies

Card Types

Member

Member Types

Payout Destinations

Payout Merchant Types

Payout Transaction Types

Payout Return Status

Payments

Payment Types

Payment Groups

Payment Status

Payment Item Confirmation Status

Payment Phases

Payment Methods

Payout Status

Payout Types

Payout Source

MD Status

Payment Sources

Alternative Payment Methods

Offline Alternative Payment Methods

Additional Actions Of Alternative Payment Methods

Category Codes

Reward Types

Refunds

Refund Status Types

Refund Status Types of Payment

Refund Types

Money Transfer

Money Transfer Request Result Status

Transferring/Withdrawing Money from/to Wallet

Types of Wallet Transfer/Withdrawal

Daily Transaction Report

Daily Transaction Report File Types

Signature Calculation

Signature Calculation Algorithm

Sample 1

Parameters

Signature Calculation

Headers to be Added on Request:

Sample 2

Parameters

Signature Calculation

Headers to be Added on Request: