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.

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=