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.
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 |
Responses given as a result of successful transactions contain different parameters depending on whether the transaction result is singular or plural.
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,
...
}
}
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
}
}
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.
Some constants and enum values used as request and response parameters of different transactions are listed under this heading.
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 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 |
Types expressing the configuration of the use of card:
Value | Description |
---|---|
CREDIT_CARD |
Credit card |
DEBIT_CARD |
Debit card |
PREPAID_CARD |
Prepaid card |
They are the names that express the card provider associations.
Value | Description |
---|---|
VISA |
Visa |
AMEX |
American Express |
MASTER_CARD |
Master Card |
TROY |
Troy |
Value | Description |
---|---|
PERSONAL |
Personal member |
PRIVATE_COMPANY |
Private Company member |
LIMITED_OR_JOINT_STOCK_COMPANY |
Limited or joint stock company member |
Value | Description |
---|---|
IBAN |
IBAN |
WALLET |
Member wallet |
Value | Description |
---|---|
MERCHANT |
Merchant |
SUB_MERCHANT_MEMBER |
Sub merchant member |
Value | Description |
---|---|
PAYMENT |
Payout for payments |
WITHDRAW |
Payout for withdraws |
RAS |
Payout for refund after settlement |
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. |
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 |
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 |
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. |
Values expressing approval status for a payment item
Value | Description |
---|---|
WAITING_FOR_APPROVAL |
Awaiting approval |
APPROVED |
Approved |
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. |
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 |
PAYPAL |
User pays with own PayPal account |
AFTERPAY |
User pays with own Afterpay account |
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 |
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 |
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 |
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 |
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 which are supported by Craftgate
Değer | Açıklama |
---|---|
PAPARA |
Papara |
PAYONEER |
Payoneer |
SODEXO |
Sodexo |
EDENRED |
Edenred |
PAYPAL |
PayPal |
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 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 |
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 |
Values that express the status of a refund.
Value | Description |
---|---|
SUCCESS |
Successful refund |
FAILURE |
Failed refund |
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 |
Values that indicate where a refund amount will be refunded.
Value | Description |
---|---|
PROVIDER |
To Provider (Card or APM) |
WALLET |
To Wallet |
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 |
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. |
Value | Description |
---|---|
CSV |
Comma Separated Values file extension. |
XLSX |
Excel file extension. |
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 |
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:
Name | Value |
---|---|
Request URL | https://api.craftgate.io/onboarding/v1/members/1 |
Request Body | - |
API Key | key-1 |
Secret Key | FooBar123! |
Random Key | Xa15Fp11T |
https://api.craftgate.io/onboarding/v1/members/1
key-1
FooBar123!
Xa15Fp11T
https://api.craftgate.io/onboarding/v1/members/1key-1FooBar123!Xa15Fp11T
y1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA=
Name | Value |
---|---|
x-api-key | key-1 |
x-rnd-key | rGciw1df |
x-auth-version | V1 |
x-signature | y1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA= |
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 |
https://api.craftgate.io/onboarding/v1/members
key-1
FooBar123!
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"}
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"}
nv8y2bSnFjYNRzVRqzkHTK5RXKuN04hoK6fLE2+nzTw=
Name | Value |
---|---|
x-api-key | key-1 |
x-rnd-key | Xa15Fp11T |
x-auth-version | V1 |
x-signature | pYuONv7/IgM14OAuSoANWUUgfVSwRX3bYeSZLXltb04= |