To get paid with Alternative Payment Method (APM), the first step is to initiate a payment on Craftgate. Afterwards, the payment will be completed by following the payment steps of the APM, which may vary depending on the selected APM. Later, the merchant is triggered with the payment status information who has been given callback URL address in the payment initiation request.
The endpoint and http method information to make a payment with APM are stated below.
HTTP Method | URL |
---|---|
POST |
/payment/v1/apm-payments/init |
Parameter Name | Type | Required | Description |
---|---|---|---|
apmType |
string |
Yes | See: Alternative Payment_Methods Alternative Payment Method type |
merchantApmId |
number |
No | ID of Alternative Payment Method which is declared in APM Management Page of Merchant Panel. It is recommended to sent if multiple APM declared in same APM Type. |
conversationId |
string |
No | "boomerang" value that can be sent with the request and received with the response. It can be used to associate different requests with each other. Usually, the order number is used that is stored in merchant own system. |
externalId |
string |
No | It is generally used as a payment order number or basket number on the merchant side. You can search with this value later by using reporting services. |
price |
decimal |
Yes | Total basket price. The sum of the item prices in the basket must be equal to total basket price. |
paidPrice |
decimal |
Yes | The final amount to be paid from the card by calculating differences such as commissions and discounts. The amount to be collected from the wallet is also included in this amount. If there is an interest in the transaction, the amount with the interest added should be entered in this parameter. |
buyerMemberId |
number |
No | ID of the buyer that is returned from member creation. |
currency |
Currency |
Yes | See: Currencies |
paymentGroup |
PaymentGroup |
Yes | See: Payment Groups |
paymentChannel |
string |
No | It is generally used to keep information specific to the payment channel on the merchant side. You can search with this value later by using reporting services. |
callbackUrl |
string |
Yes | The URL to be used to send the result returned from the APM to the merchant |
apmOrderId |
string |
No | Order id parameter to be transmitted to the APM when receiving the payment. Since it is optional, it is recommended not to send it and the orderId value is generated by Craftgate. |
clientIp |
string |
No | IP of the buyer. |
items |
PaymentItem[] |
Yes | (See. Payment Item Information) Payment items related to payment. You must send at least one payment item and the sum of prices must be equal to the price field. |
additionalParams |
map<string, map> |
No | Additional parameters related to payment. |
The parameters returned as a result of the payment transaction with APM are subject to the rules specified in the
Response Formats section of the API documentation home page. In the absence of a systematic or
fictional error, the sub-parameters of the object returned in the data
parameter are as follows:
Parameter Name | Type | Always Exist | Description |
---|---|---|---|
paymentId |
number |
Yes | Payment Id |
paymentStatus |
PaymentStatus |
No | Represent payment status |
additionalAction |
AdditionalAction |
No | Sometimes you should do another step for complete APM payment. There is no any step when additionalAction is NONE . For more information, see. APM Additional Actions |
redirectUrl |
string |
Yes | Redirect URL of the APM |
paymentError |
PaymentError |
No | The detail about errors if any error occurred while APM payment. |
The following parameters are forwarded as form variables using the HTTP POST method. The parameters included in the
request to callbackUrl
by Craftgate after validation are as follows:
Parameter Name | Type | Always Exist | Description |
---|---|---|---|
status |
string |
Yes | Represents APM verification status. Returns SUCCESS or FAILURE . |
conversationId |
string |
No | Value of theconversationId parameter sent in the 3DSecure payment initiation |
paymentId |
number |
No | ID of the payment which is sent when the verification is successful. |
callbackStatus |
string |
No | Sent as a parameter, in case the APM or end user triggers the 3DS verification step again and the payment has been verified before. Status parameter will be FAILURE and callbackStatus parameter will be ALREADY_RETURNED . In case this field comes with the value of ALREADY_RETURNED , the status of the payment should be checked in your system and no action should be taken if it is completed. |
hash |
string |
Yes | Response parameters hash value with Sha-256 Hex algorithm. You can find details below on "Creating Hash Value". |
You can make hash validation response with your hash value. You need to use Sha-256 Hex Algorithm to create hash value.
threedSecureCallbackKey###status###completeStatus###paymentId###conversationData###conversationId ###callbackStatus
Example of hashing procedure for following response is below. Assume that Üye İşyeri 3DSecure Callback Key value as "merchantThreeDsCallbackKeySndbox".
{
"status": "SUCCESS",
"conversationId": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
"paymentId": 1,
"callbackStatus": null,
"hash": "520c04646748d344fa5541aacaf56cb0d727c5b3020e09c554604f81b9015d0a"
}
Input value for hashing should be like:
merchantThreeDsCallbackKeySndbox###SUCCESS###1###456d1297-908e-4bd6-a13b-4be31a6e47d5###
You can hash this value via Sha-256 Hex algorithm with Üye İşyeri 3DSecure Callback Key value. Result must be equal with hash value which contains in response.
You should complete APM payment if paymentStatus
is WAITING
and additionalAction
is not equal to NONE
returned
to you while initializing APM payment.
The endpoint and http method information to make a payment with APM are stated below.
HTTP Metod | URL |
---|---|
POST |
/payment/v1/apm-payments/complete |
Parameter Name | Type | Required | Description |
---|---|---|---|
paymentId |
number |
Yes | Payment id |
additionalParams |
map<string, map> |
Yes | Additional parameters related to complete payment. |
Parameters returned as a result of payment are also subject to the rules specified in
the Response Formats section of the API documentation home page. In the absence of a systematic
or fictional error, the sub-parameters of the object returned in the data
parameter are as follows:
Parameter Name | Type | Always Exist | Description |
---|---|---|---|
paymentId |
number |
Yes | ID of the payment. |
paymentStatus |
PaymentStatus |
Yes | See: Payment Status |
paymentError |
PaymentError |
No | The detail about errors if any error occurred while APM payment. |