Skip to main content

Payment with YKB WorldPay

To get paid with YKB WorldPay, the first step is to initiate a payment on Craftgate. Afterward, the payment process is completed by the user through World Pay mobile application. Later, for WEB2QR and WEB2APP flow, merchant is triggered with the payment status information who has been given callback URL address in the payment initiation request. For APP2APP flow user redirect to redirectUrl which has been set in init request by merchant. After redirection, merchant calls complete service and finishes payment.

Payment initiation with YKB WorldPay

URL

The endpoint and http method information to make a payment with YKB WorldPay are stated below.

POST/payment/v1/pos-apm-payments/init

Payment initiation request parameters

price
decimal
required

Total basket price. The sum of the item prices in the basket must be equal to total basket price.

paidPrice
decimal
required

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.

posAlias
string

Represents the POS that payment will be collected.

currency
Currency
required
Values:
TRY
USD
EUR
GBP
CNY
ARS
BRL
AED
IQD
AZN
KZT
conversationId
string

"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

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.

callbackUrl
string
required

The URL to be used to send the result returned from the bank to the merchant

paymentGroup
PaymentGroup
Values:
PRODUCT
LISTING_OR_SUBSCRIPTION
paymentPhase
PaymentPhase
required

Only AUTH supports. see: Payment Phases

Values:
AUTH
PRE_AUTH
POST_AUTH
paymentChannel
string

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.

buyerMemberId
number

ID of the buyer that is returned from member creation.

bankOrderId
string

Order id parameter to be transmitted to the bank 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

IP of the buyer.

items
PaymentItem[]
required

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
required

Additional parameters related to payment

installments
PosApmInstallment[]

WorldPay installment information. If not sent, payment processed as pos commission settings

paymentProvider
PaymentProvider
required
Values:
YKB_WORLD_PAY
fraudParams
FraudCheckParameters

Parameters that can be sent for Fraud check. (See. Fraud Check Parameters)

Response Parameters

The parameters returned as a result of the payment transaction with World Pay 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:

htmlContent
string

Available for web flow. WorldPay HTML that will be shown to user. Return value must be base64-decoded.

paymentId
number

ID of the payment

paymentStatus
PaymentStatus
Values:
FAILURE
SUCCESS
INIT_THREEDS
CALLBACK_THREEDS
WAITING
additionalAction
AdditionalAction

Show html content to customer when status SHOW_HTML_CONTENT

Values:
CONTINUE_IN_CLIENT
SHOW_HTML_CONTENT
REDIRECT_TO_URL
NONE
additionalData
map<string, map>

Additional information about payment.

Parameters Forwarded to Callback URL

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:

status
string

Represents World Pay verification status. Returns SUCCESS or FAILURE.

conversationId
string

Value of theconversationId parameter sent in the payment initiation

paymentId
number

ID of the payment which is sent when the verification is successful.

callbackStatus
string

Sent as a parameter, n case the bank 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.

conversationData
string

Returns this security parameter when response status success. Need to send this value in complete step.

hash
string

Response parameters hash value with Sha-256 Hex algorithm. You can find details below on "Creating Hash Value".

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.

  • You can reach 32 characters key value from following: Merchant Panel -> Yönetim -> Üye İşyeri Ayarları -> "Üye İşyeri 3DSecure Callback Key"
  • You need to prepare input value as in order. Also you need to put "###" as delimiter between parameters.
  • For null values please put empty string ("").

threedSecureCallbackKey###status###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": "d1811bb0-25a2-40c7-ba71-c8b605259611",
"paymentId": 317832,
"callbackStatus": null,
"conversationData": null,
"hash": "a000cc69dbe88349df1917f7dd8546607623f8edbaa79a6b1ebc1834803d847e"
}

Input value for hashing should be like:

TjaHHdMbguUSonMEUr4tR42IC0UEtHPb###SUCCESS###317832######d1811bb0-25a2-40c7-ba71-c8b605259611###

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.

Sample Codes

You can review the sample codes in the open source Craftgate API clients.

Payment initiation with YKB WorldPay

YKB WorldPay Payment Complete

For APP2APP flow, after bank redirection this service should be calling from merchant. Then payment finishes.

URL

The endpoint and http method information used to complete POS APM payment are stated below.

POST/payment/v1/apm-payments/complete

Complete Payment Request Params

paymentId
number
required

POS APM Ödeme başlatma isteğinin cevabında yer alan ödeme ID değeri

Response Parameters

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:

id
number

ID of the payment.

createdDate
date

The date that payment is created

price
decimal

Basket price of the payment

paidPrice
decimal

Paid price of the payment

walletPrice
decimal

Wallet price of the payment

currency
Currency
Values:
TRY
USD
EUR
GBP
CNY
ARS
BRL
AED
IQD
AZN
KZT
buyerMemberId
number

Buyer member ID of the payment

installment
number

Installment number

conversationId
string

Value of theconversationId parameter sent in the payment request

externalId
string

externalId value that sent in payment request by merchant

paymentType
PaymentType
Values:
CARD_PAYMENT
DEPOSIT_PAYMENT
WALLET_PAYMENT
CARD_AND_WALLET_PAYMENT
BANK_TRANSFER
APM
paymentGroup
PaymentGroup
Values:
PRODUCT
LISTING_OR_SUBSCRIPTION
paymentSource
PaymentSource
Values:
API
CHECKOUT_FORM
PAY_BY_LINK
paymentStatus
PaymentStatus
Values:
FAILURE
SUCCESS
INIT_THREEDS
CALLBACK_THREEDS
WAITING
paymentPhase
PaymentPhase
Values:
AUTH
PRE_AUTH
POST_AUTH
paymentChannel
string

paymentChannel value sent by the merchant in the payment request

isThreeDS
boolean

Indicates whether the payment is 3D Secure payment

merchantCommissionRate
decimal

Interest rate to calculate paid price that buyer will pay

merchantCommissionRateAmount
decimal

Interest amount. Equal to the difference between paidPrice and price values

bankCommissionRate
decimal

Bank commission rate

bankCommissionRateAmount
decimal

Bank commission rate amount

cardUserKey
string

Card user key that represents the card holder.

cardToken
string

Card token that represents the card.

paidWithStoredCard
boolean

Indicates whether the payment was made with a stored card

binNumber
string

Exist for the payments fully or partially collected from the card. First 8 digits of the card

lastFourDigits
string

Exist for the payments fully or partially collected from the card. Last 4 digits of the card

cardHolderName
string

Card holder name surname

bankCardHolderName
string

Card holder name surname retrieved from bank. The return value might be null for PF poses

authCode
string

authCode value retrieved from bank related to the payment. The return value might be null for PF poses

hostReference
string

hostReference value retrieved from bank related to the payment

transId
string

transId value retrieved from bank related to the payment. The return value might be null for PF poses

orderId
string

orderId value retrieved from bank related to the payment

cardType
CardType

(See: Card Types)

Values:
CREDIT_CARD
DEBIT_CARD
PREPAID_CARD
cardAssociation
CardAssociation

Card Association

Values:
VISA
MASTER_CARD
AMEX
TROY
JCB
UNION_PAY
MAESTRO
DISCOVER
DINERS_CLUB
cardBrand
string

Brand of card. Exist for the payments fully or partially collected from the card

requestedPosAlias
string

Value of theposAlias parameter sent in the payment request

pos
MerchantPos

POS info that payment is received

loyalty
Loyalty

Loyalty info that used in payment (See: Reward Usage)

fraudId
number

Fraud Check Id if fraud rule matches (See: Fraud Checks)

fraudAction
FraudAction

Fraud Check Action if fraud rule matches (See: Fraud Actions)

Values:
BLOCK
REVIEW
paymentTransactions
PaymentTransaction[]

It includes the transaction information sent when making the payment request, and the pricing and money transfer information of the payment based on these transactions

additionalData
map<string, map>

Additional data related to the payment

Sample Codes

You can review the sample codes in the open source Craftgate API clients.