Credit Card Approval API (Deferred Capture)

A credit card payment API that processes authentication and capture separately. After authentication is completed, the capture request is submitted as a separate step.

Test Key Information

Important Notes

Deferred Capture Method

You must use the merchant order number (mchtTrdNo) created during the authentication request, and authTrdNo must be the transaction number received upon successful authentication.

This API performs only the capture step separately after authentication is completed.
The merchant order number used during authentication and the authentication transaction number are required.
Billkey issuance requires a separate service activation.

API Information

POST/spay/APIService.do

Content-Typeapplication/json

테스트https://tbgw.settlebank.co.kr/spay/APIService.do

운영https://gw.settlebank.co.kr/spay/APIService.do

Request Parameters

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*Unique merchant ID assigned by Hecto Financial

Unique merchant ID assigned by Hecto Financial

└verAN(4)Alphanumeric, up to 4 bytes*Message version

Message version

*Fixed value

└methodA(2)Alphabetic, up to 2 bytes*Payment method

Payment method

*Fixed value

└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code

Business type code

*Fixed value (for capture)

└encCdN(2)Numeric, up to 2 bytes*Encryption type code

Encryption type code

*Fixed value

└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number (must use the number created during the authentication request)

Merchant order number (must use the number created during the authentication request)

└trdDtN(8)Numeric, up to 8 bytes*Request date (YYYYMMDD)

Request date (YYYYMMDD)

└trdTmN(6)Numeric, up to 6 bytes*Request time (HHMMSS)

Request time (HHMMSS)

└mobileYnA(1)Alphabetic, up to 1 bytesMobile indicator

Mobile indicator

Y: Mobile web/app N: PC or other

└osTypeA(1)Alphabetic, up to 1 bytesOS type

OS type

A: Android I: IOS W: Windows M: Mac E: Other

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*SHA-256Hash value generated using SHA256(실시간 생성)

Hash value generated using SHA256

NOTE

Hash Generation Combination

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey

└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64Transaction amount

Transaction amount

└authTrdNoAN(40)Alphanumeric, up to 40 bytes*Authentication transaction number (transaction number received upon successful authentication)

Authentication transaction number (transaction number received upon successful authentication)

Response Parameters

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*Unique merchant ID assigned by Hecto Financialnxca_jt_hd

Unique merchant ID assigned by Hecto Financial

└verAN(4)Alphanumeric, up to 4 bytes*Message version0A19

Message version

*Fixed value

└methodA(2)Alphabetic, up to 2 bytes*Payment methodCA

Payment method

*Fixed value

└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type codeB2

Business type code

*Fixed value for capture

└encCdN(2)Numeric, up to 2 bytes*Encryption type code23

Encryption type code

*Fixed value

└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order numberORDER20211231100000

Merchant order number

└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number issued by Hecto FinancialSOFP_PGMPnxhp_sb_hd0211021111808M1234567

Unique transaction number issued by Hecto Financial

└trdDtN(8)Numeric, up to 8 bytes*Request date (YYYYMMDD)20211231

Request date (YYYYMMDD)

└trdTmN(6)Numeric, up to 6 bytes*Request time (HHMMSS)100000

Request time (HHMMSS)

└outStatCdN(4)Numeric, up to 4 bytes*Transaction status code0061

Transaction status code

0061: Authentication success (authentication step) 0021: Capture success (capture step) 0031: Failure

*In the deferred capture method, 0061 is returned at the authentication step and 0021 at the capture step.

└outRsltCdN(4)Numeric, up to 4 bytes*Result code. Detailed code provided when transaction status is '0031'0000

Result code. Detailed code provided when transaction status is '0031'

*Refer to the decline code table

└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message (URL Encoding, UTF-8)Processed successfully.

Result message (URL Encoding, UTF-8)

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*Hash value from request returned as-is

Hash value from request returned as-is

└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5PaddingTransaction amount1000

Transaction amount

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesRequest value returned as-is in responsename=HongGilDong&age=25

Request value returned as-is in response

└apprNoN(15)Numeric, up to 15 bytesCredit card approval number30001234

Credit card approval number

└intMonN(2)Numeric, up to 2 bytesCredit card installment months00

Credit card installment months

└fnNmAH(20)Alpha + Korean, up to 20 bytesCredit card company nameWoori Card

Credit card company name

└fnCdAN(4)Alphanumeric, up to 4 bytesCredit card company codeLTC

Credit card company code

└pointTrdNoAN(40)Alphanumeric, up to 40 bytesPoint transaction number (for Point Damoa combined payment)STFP_PGCAnxca_jt_il0211129135810M1494620

Point transaction number (for Point Damoa combined payment)

└pointTrdAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5PaddingPoint transaction amount (for Point Damoa combined payment)1000

Point transaction amount (for Point Damoa combined payment)

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└cardTrdAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5PaddingCredit card payment amount excluding discounts/points4000

Credit card payment amount excluding discounts/points

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└billKeyAN(50)Alphanumeric, up to 50 bytesBillkey (recurring payment token)SBILL_0123456789

Billkey (recurring payment token)

*Requires separate service activation. Contact your account manager.

└dcTrdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5PaddingDiscount transaction amount1000

Discount transaction amount

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└dcYnA(1)Alphabetic, up to 1 bytes*Discount indicatorY

Discount indicator

Y: Discount amount exists N: No discount amount

└ninstmtTypeCdA(1)Alphabetic, up to 1 bytesInterest-free installment typeY

Interest-free installment type

Y: Interest-free N: Regular installment/full payment

└cardNoAN(20)Alphanumeric, up to 20 bytesAES-256AES-256/ECB/PKCS5PaddingCard number (masked, optional based on merchant settings)123456******7890

Card number (masked, optional based on merchant settings)

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└ornPntUseYnA(1)Alphabetic, up to 1 bytesCard company points usage indicatorY

Card company points usage indicator

Y: Used N: Not used

└ornPntAmtA(12)Alphabetic, up to 12 bytesAES-256AES-256/ECB/PKCS5PaddingCard company points usage amount1000

Card company points usage amount

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

Request Example

{
  "params": {
    "mchtId": "nxca_jt_hd",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B2",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdDt": "20211231",
    "trdTm": "100000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "980f95d9b059dd15394eeb39e9d7bc8b3500f9afa4a38bea10877cd46a42caf6",
    "trdAmt": "AES-encrypted amount",
    "authTrdNo": "SOFP_PGMPnxhp_sb_hd0211021111808M1234567"
  }
}

Response Examples

Success Response

{
  "params": {
    "mchtId": "nxca_jt_hd",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B2",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "SOFP_PGMPnxhp_sb_hd0211021111808M1234567",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "Processed successfully."
  },
  "data": {
    "pktHash": "980f95d9b059dd15394eeb39e9d7bc8b3500f9afa4a38bea10877cd46a42caf6",
    "trdAmt": "AES-encrypted amount",
    "apprNo": "30001234",
    "intMon": "00",
    "fnNm": "Woori Card",
    "fnCd": "LTC",
    "billKey": "SBILL_0123456789",
    "dcTrdAmt": "AES-encrypted discount amount",
    "dcYn": "Y",
    "ninstmtTypeCd": "N"
  }
}

Failure Response

{
  "params": {
    "mchtId": "nxca_jt_hd",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B2",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0031",
    "outRsltCd": "1001",
    "outRsltMsg": "Missing payment request information"
  },
  "data": {
    "pktHash": "980f95d9b059dd15394eeb39e9d7bc8b3500f9afa4a38bea10877cd46a42caf6"
  }
}

Response Codes

Transaction Status Codes (outStatCd)

Code	Description	Note
0061	Authentication success	Authentication step of deferred capture method
0021	Capture success	Capture step of deferred capture method
0031	Failure	See outRsltCd for details
0051	Virtual account number issued	Virtual account issuance

PG Common Response Codes (outRsltCd)

Code	Description
0000	Processed successfully
0009	User cancelled
1001	Missing required payment information (merchant ID)
1002	Missing required payment information (version)
1003	Missing required payment information (payment method)
1004	Missing required payment information (business type code)
1005	Missing required payment information (merchant order number)
1006	Missing required payment information (request date)
1007	Missing required payment information (request time)
1008	Missing required payment information (hash value)
1009	Missing required payment information (transaction amount)
1010	Missing required payment information (encryption type code)
1011	Missing required payment information (transaction number)
1012	Missing required payment information (cancellation amount)
1013	Missing required payment information (refund amount)
1101	Payment request information length error (merchant ID)
1102	Payment request information length error (version)
1103	Payment request information length error (payment method)
1104	Payment request information length error (business type code)
1105	Payment request information length error (merchant order number)
1106	Payment request information length error (request date)
1107	Payment request information length error (request time)
1108	Payment request information length error (hash value)
1109	Payment request information length error (transaction amount)
1110	Payment request information length error (encryption type code)
1111	Payment request information length error (transaction number)
1112	Payment request information length error (cancellation amount)
1113	Payment request information length error (refund amount)
1901	Hash value mismatch error
1902	Encrypted field not processed error
2001	Security number mismatch
2002	Security number input timeout
2003	Security number input attempts exceeded
5001	Invalid access path (merchant information not found)
5002	Invalid access path (merchant inactive)
5003	Invalid access path (payment method not contracted)
5004	Invalid access path (payment method inactive)
5005	Invalid access path (business type not supported)
5006	Invalid access path (IP blocked)
9001	Gateway internal error
9002	Gateway communication error
9003	Gateway database error
9004	Gateway timeout
9901	Issuer system maintenance
9902	Issuer system failure
9903	Issuer communication error
9904	Issuer timeout
9905	Issuer response error

Credit Card Specific Response Codes (outRsltCd)

Code	Description
CA01	Issuer under maintenance
CA02	Issuer system failure
CA20	Invalid card expiration date
CA65	Merchant not contracted for authenticated transactions
CA82	Please call card company
CA83	This transaction cannot be cancelled

Need technical support?

Code Samples

HectoFinancial GitHub