English

简体中文

English

简体中文

Payment ​

The Genstore payment business domain is the core business module that manages payment information by providing a series of RESTful interfaces, supporting sub domains such as order placement, refund actions, and payment order queries in the payment process.

Core functions

  • Order: Create a payment order based on the order and notify PSP for deduction.
  • Refund: According to the after-sales agreement, the refund will be given to the customer.
  • Obtain a single payment order: Retrieve detailed information of the payment order based on the payment order ID associated with the order.

Application scenarios

  • Payment Extersion: Developers can use payment development capabilities to connect third-party payment service providers to their stores as a third-party payment channel to expand their store's payment capabilities.

Endpoints

GET Get refund details

POST Refund operation

GET Get payment

POST Void operation

POST Capture operation

POST Credit card payment

POST Offsite payment operation

GET Get refund details ​

Get refund details.

Request Params

refundIdstringrequired
The unique identifier for the refund attempt.

Response Data

channelRefundIdstringrequired
Refund ID from the payment provider.
statusstringrequired
The refund status (PROCESSING/SUCCESS/FAILURE).
errorstring
Error message returned when payment provider processing fails.
bash
{
	"refundId":"1234"
}
json
HTTP/1.1 200 OK
{
  "channelRefundId": "1112",
  "error": "Refund failed",
  "status": "PROCESSING"
}

POST Refund operation ​

Create a refund request.

Request Params

refundIdstringrequired
The unique identifier for the refund attempt.
paymentIdstringrequired
The ID of the original payment that is to be refunded.
amountstringrequired
The amount to be refunded.
testbooleanrequired
Indicates whether the refund is in test or live mode.

Response Data

channelRefundIdstringrequired
Refund ID from the payment provider.
errorstring
Error message returned when payment provider processing fails.
bash
{
	"amount":"100",
	"test":"true or false",
	"paymentId":"1111",
	"refundId":"1111"
}
json
HTTP/1.1 200 OK
{
  "channelRefundId": "1111",
  "error": "Refund failed."
}

GET Get payment ​

Get payment details.

Request Params

paymentIdstringrequired
Unique identifier for the payment attempt.

Response Data

statusstringrequired
The payment status (PROCESSING/SUCCESS/AUTH_SUCCESS/FAILURE)
channelPaymentIdstringrequired
Payment ID from the payment provider.
errorstring
Error message returned when payment provider processing fails.
bash
{
	"paymentId":"111"
}
json
HTTP/1.1 200 OK
{
  "channelPaymentId": "111",
  "error": "Not found payment information.",
  "status": "PROCESSING"
}

POST Void operation ​

Create an void request.

Request Params

voidIdstringrequired
The unique identifier for the void attempt.
paymentIdstringrequired
The ID of the authorized payment that is to be voided.
testbooleanrequired
Specify whether it is in test mode.

Response Data

channelVoidIdstring
Void ID from the payment provider.
errorstring
Error message returned when payment provider processing fails.
bash
{
	"test":"true or false",
	"voidId":"11122",
	"paymentId":"222"
}
json
HTTP/1.1 200 OK
{
  "channelVoidId": "xxxx",
  "error": "Cancel caputue failed"
}

POST Capture operation ​

Create a capture request.

Request Params

captureIdstringrequired
The unique identifier for the capture attempt.
paymentIdstringrequired
The ID of the authorized payment that is to be captured.
amountstringrequired
The amount to be captured. The value is always sent using a decimal point as a separator, regardless of locale.
testbooleanrequired
Whether it is in test mode (true or false).

Response Data

channelCaptureIdstring
Captureid from the payment provider.
errorstring
The reason for the failure to capture on the payment provider side.
bash
{
	"amount":"200",
	"test":"true",
	"paymentId":"2222",
	"captureId":"1111"
}
json
HTTP/1.1 200 OK
{
  "channelCaptureId": "3333",
  "error": "Capture failed"
}

POST Credit card payment ​

Create a payment request to pay with a credit card.

Request Params

paymentIdstringrequired
Unique identifier for the payment action.
amountstringrequired
The payment amount.
currencystringrequired
Three-letter ISO 4217 currency code.
testbooleanrequired
Specify whether it is test mode.
paymentMethodobjectrequired
The payment information.
+ Show child properties
customerobjectrequired
The buyer's information.
+ Show child properties
manualCapturebooleanrequired
Payment capture type (true for automatic capture, false for manual capture).
clientDetailsobjectrequired
The buyer's browser information.
+ Show child properties
purchaseInfoobject
Products information.
+ Show child properties

Response Data

threeDsUrlstring
URL returned when payment requires 3D-Secure verification.
errorstringrequired
Error message returned when payment channel processing fails.
bash
{
	"purchaseInfo":{
		"insurance":"1",
		"itemTotal":"100",
		"shipping":"1",
		"taxTotal":"1",
		"discount":"1",
		"handling":"1",
		"shippingDiscount":"0.0",
		"items":[
			{
				"unitPrice":"1.0",
				"imgUrl":"http://xxxx.com",
				"quantity":"2",
				"name":"Black Cotton T-Shirt and White Denim Shorts",
				"description":"Casual Black Cotton T-Shirt and White Denim Shorts for Everyday Wear",
				"tax":"2.0",
				"category":"1",
				"sku":"107369095352924",
				"virtualProduct":"true or false"
			}
		]
	},
	"amount":"200.00",
	"clientDetails":{
		"acceptLanguage":"zh,en-US;q=0.9,en;q=0.8,zh-CN;q=0.7",
		"ipAddress":"10.5.2.2",
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
	},
	"test":"true",
	"manualCapture":"true",
	"paymentId":"PI00202410161331562671",
	"paymentMethod":{
		"data":{
			"cipherText":"I/ehfE/1SkDx/i8qJgoe/qXaRV+fyaVIeEL7D+5PWiPtOgZZAQ/GWvRbI7kgOV0dCkH/uhb0Nlq4sns6GWgf7GeiezxKjPdaJqqbdnYvb3y98SG6DWzCDTc+Za6bpkk2uAg=",
			"salt":"GENSTORE-HKDF-SALT",
			"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAECYaybEr5VfuEUOTBN5iYi3FLDhVUx0s1k6K4iUqk+rgnHRovbXKlItHNzTeGSSevunb8HdQEaPclqUfAps07Uw==",
			"suit":"GENSTORE-V1",
			"returnUrl":"https://www.xxx.shop/pay/result",
			"iv":"GUdwmcbLCp+4hHMr"
		}
	},
	"currency":"USD",
	"customer":{
		"phoneNumber":"+8618800008888",
		"shippingAddress":{
			"phoneNumber":"+8615885555",
			"province":"NY",
			"city":"Westbury",
			"countryCode":"US",
			"givenName":"John",
			"familyName":"Smith",
			"postalCode":"10013",
			"company":"IBM",
			"line2":"Apartment 5",
			"line1":"2063  Marshville Road"
		},
		"billingAddress":{
			"phoneNumber":"+8615885555",
			"province":"NY",
			"city":"Westbury",
			"countryCode":"US",
			"givenName":"John",
			"familyName":"Smith",
			"postalCode":"10013",
			"company":"IBM",
			"line2":"Apartment 5",
			"line1":"2063  Marshville Road"
		},
		"email":"xxx@gmail.com"
	}
}
json
HTTP/1.1 200 OK
{
  "error": "Payment failed",
  "threeDsUrl": "http://xxx.com"
}

POST Offsite payment operation ​

Create a payment request that redirects to a third-party website.

Request Params

paymentIdstringrequired
Unique identifier for the payment action.
amountstringrequired
The amount to be charged. The value is always sent using a decimal point as a separator, regardless of locale.
currencystringrequired
Three-letter ISO 4217 currency code.
testbooleanrequired
Indicates whether the payment is in test or live mode.
paymentMethodobjectrequired
The payment information.
+ Show child properties
customerobjectrequired
The buyer's information.
+ Show child properties
manualCapturebooleanrequired
Payment capture type (true for automatic capture, false for manual capture).
purchaseInfoobjectrequired
The products information.
+ Show child properties

Response Data

redirectUrlstringrequired
The payment address returned by the payment provider.
errorstringrequired
Error message returned when payment provider processing fails.
bash
{
	"purchaseInfo":{
		"insurance":"0.0",
		"itemTotal":"50.0",
		"shipping":"0.0",
		"taxTotal":"5.5",
		"discount":"0.0",
		"handling":"0.0",
		"shippingDiscount":"0.0",
		"items":[
			{
				"unitPrice":"1.0",
				"imgUrl":"http://xx.com",
				"quantity":"2",
				"name":"Black Cotton T-Shirt and White Denim Shorts",
				"description":"Casual Black Cotton T-Shirt and White Denim Shorts for Everyday Wear",
				"tax":"1.0",
				"category":"1",
				"sku":"107369095352924",
				"virtualProduct":"true"
			}
		]
	},
	"amount":"100.80",
	"test":"true",
	"manualCapture":"true",
	"paymentId":"PI00202410161331562671344",
	"paymentMethod":{
		"data":{
			"cancelUrl":"http://test.genstore.ai/xx",
			"returnUrl":"https://www.xxx.shop/pay/result"
		}
	},
	"currency":"USD",
	"customer":{
		"phoneNumber":"+8618800008888",
		"shippingAddress":{
			"phoneNumber":"+8618800008888",
			"province":"NY",
			"city":"New York",
			"countryCode":"US",
			"givenName":"John",
			"familyName":"Smith",
			"postalCode":"10013",
			"company":"IBM",
			"line2":"Apartment 5",
			"line1":"2063  Marshville Road"
		},
		"billingAddress":{
			"phoneNumber":"+8618800008888",
			"province":"NY",
			"city":"New York",
			"countryCode":"US",
			"givenName":"John",
			"familyName":"Smith",
			"postalCode":"10013",
			"company":"inter",
			"line2":"Apartment 5",
			"line1":"2063  Marshville Road"
		},
		"email":"xx@gmail.com"
	}
}
json
HTTP/1.1 200 OK
{
  "redirectUrl": "https://www.xxx.com/",
  "error": "Transaction do not honor"
}